Setup for Plastic SCM testing
When changing the segment_plastic.go file, you may need to test your changes against an actual instance of
Plastic SCM. This doc should bring you up to speed with Plastic SCM.
In the contributing doc there is a section about dev containers & codespaces. You can set up Plastic SCM inside these as well.
Server Setup
Here you can find the official setup instructions. I'll describe it in short:
Installation on Debian or in dev-container
First add the repo:
sudo apt-get update
sudo apt-get install -y apt-transport-https
echo "deb https://www.plasticscm.com/plasticrepo/stable/debian/ ./" | sudo tee /etc/apt/sources.list.d/plasticscm-stable.list
wget https://www.plasticscm.com/plasticrepo/stable/debian/Release.key -O - | sudo apt-key add -
sudo apt-get update
Then install the server: this might throw an error at the end of the setup see below
sudo apt-get install plasticscm-server-core
This might show an error while configuring the installed package. In that case the server was nod registered as a service. Ignore it!
Server configuration
Configuring the server is done via:
cd /opt/plasticscm5/server/
sudo ./plasticd configure
You are asked 5 questions. Choose these options:
- 1: English
- 8087 (default port, just hit return)
- 8088 (default ssl port, just hit return)
- 1: NameWorkingMode (use local users and groups)
- skip license token (just hit return)
Congrats! Your server is configured. You can find out more in the official configuration instructions.
Run Server
If your server installed without an error, it was correctly registered as a server and can be started via:
sudo service plasticd start
If not, you need to start it manually (for example inside the dev-container):
cd /opt/plasticscm5/server/
sudo ./plasticd start
This will lock the current shell until the server process finishes. You might need to open another terminal to continue.
Your Plastic SCM server should be started now.
Client Setup
Plastic SCM comes, much like git, with a CLI (+ client UI [optional])
Installation on Debian or in dev-container
These are the steps to install the Plastic SCM CLI on Debian or in the dev-container:
sudo apt-get install plasticscm-client-core
Client configuration
To connect the client to the server and set up an account run:
clconfigureclient
You are asked a few questions. Choose these options:
- 1: English
- localhost (just hit return)
- default port 8087 (just hit return)
- No SSL (just hit return)
- No Proxy (just hit return)
Congrats! Your client should now be connected to your server.
You can test if it worked and display some license info via:
cm li
Testing stuff
Now to the fun part! The server is automatically set up to host a default repo with the branch /main.
The Plastic SCM CLI command is: cm
If you ever wonder what you can do with it call:
cm showcommands --all`
Creating a local workspace
You need a local workspace to work with plastic:
cd ~
mkdir dev
cd dev
cm wk create workspace workspace rep:default
cd workspace
cm status
Adding files
Start by creating local, private files
echo "test" > myfile.txt
cm status --all
Add the file to your local changes
cm add myfile.txt
cm status
Test hint: Both Private and Added files should be counted towards the Added property of the plastic segment.
Committing changes
After locally adding, changing, moving or deleting files you want to commit them to create a new changeset. Run this command to commit all local changes:
cm status | cm ci . -c "my first commit"
Undoing local changes
Just in case you don't want or can't commit your local changes, there is an undo command. This will undo all local changes:
cm status | cm undo .
Changing, moving or deleting files
All these actions are done on the file level. You can run cm status to see your actions beeing tracked by plastic.
Use the commit method described above to commit your changes.
Test hint: All these changes should be counted by the designated property (Modified, Moved, Deleted)
of the plastic segment.
Branching
Above the basics of handling the Plastic SCM client are described. But you would want to dive deeper and use branches or labels and merge them.
Create a new branch
To create a new branch based on the latest changeset on branch /main call
cm br /main/new-branch
Hint: To list all branches use
cm find branches
Set a label to the current changeset
Your workspace will always reflect one specific changeset (see cm status). You can set a label on that changeset for
fast navigation or documentation purposes
cm label mk "BL0001"
Hint: To list all labels use
cm find labels
Switch your local workspace to a branch
To switch to a branch use
cm switch /main/new-branch
cm status
Test Hint: the branch name should be reflected in the Selector property of the plastic segment
Switch to a changeset
Each commit gets a unique changeset number. You can switch to these via
cm switch cs:1
Test Hint: the changeset should be reflected in the Selector property of the plastic segment
Switch to a label
You can also switch to a label via
cm switch BL00001
Test Hint: the label should be reflected in the Selector property of the plastic segment
Merge a branch
To merge a branch you have to switch to the destination branch of the merge. After that you can merge another branch via
cm switch /main
cm merge /main/new-branch --merge
cm status
Hint: This will only prepare the merge locally. You will have to commit the changes to complete the merge!
Test Hint: A pending merge should be reflected in the MergePending property of the plastic segment
Cherry-pick merge
While the merge above will merge all changes from a branch (and his parents), there is a cherry-pick merge, which will merge only the changes of one single changeset
cm merge cs:8 --merge --cherrypicking
Hint: This will only prepare the merge locally. You will have to commit the changes to complete the merge!
Test Hint: A pending cherry-pick merge should be reflected in the MergePending property of the plastic segment
Merge conflicts
There are multiple causes for conflicts while merging
Evil Twin
This happens when a merge is performed where two files with the same name were added on both the source and destination branch.
cm br mk /main/sub-branch
cm switch /main/sub-branch
echo "1" > twin.txt
cm add twin.txt
cm ci twin.txt
cm switch /main
echo "2" > twin.txt
cm add twin.txt
cm ci twin.txt
cm merge /main/sub-branch --merge
Hint: this will prompt you to directly resolve the conflict
Changed on both sides
This happens when a merge is performed where a file was changed on both sides: source and destination
cm switch /main
echo "base" > file.txt
cm add file.txt
cm ci file.txt
cm br mk /main/test
echo "on main" > file.txt
cm ci file.txt
cm switch /main/test
echo "on test" > file.txt
cm ci file.txt
cm switch /main
cm merge /main/test --merge
Hint: this will try to open gtkmergetool which will fail inside the dev-container!
Changed vs. deleted file
This happens when a merge is performed where a file was modified on one side and deleted on the other side of the merge
cm switch /main
echo "base" > deleteme.txt
cm add deleteme.txt
cm ci deleteme.txt
cm br mk /main/del
rm deleteme.txt
cm ci --all
cm switch /main/del
echo "on del" > deleteme.txt
cm ci deleteme.txt
cm switch /main
cm merge /main/del --merge
Hint: This will prompt you to directly resolve the merge conflict