The Wiert Corner – irregular stream of stuff

Jeroen W. Pluimers on .NET, C#, Delphi, databases, and personal interests

  • My badges

  • Twitter Updates

  • My Flickr Stream

  • Pages

  • All categories

  • Enter your email address to subscribe to this blog and receive notifications of new posts by email.

    Join 2,356 other followers

PlasticSCM memories

Posted by jpluimers on 2020/12/23

Spending most of your career as an independent contractor, you bump into a lot of toolchains.

Part of those toolchains usually involved (and by now surely should involve) version control for both development and infrastructure configuration management.

I remember PlasticSCM quite well.

The really good part is the branch overview (called Branch Explorer) in the PlasticSCM UI, as it is:

They also have frequent updates, which however are hard to discover because there is no built-in update mechanism that notifies you of them.

Those updates are badly needed, because I kept bumping into bugs. Which is odd, because I bumped into far less issues when using UI layers for SVN, TFS, Mercurial and git (SourceTree being a major exception, but they seem to have recovered from a long period of bad versions a few years back).

So here are some of my gripes, that might have been fixed by now.

Main console tool

Let’s start with the main console tool called cm which lacks a lot of documentation, and the documentation there is, is sparse.

The main documentation is in [WayBack] Plastic SCM version control · CLI guide: “Tutorial that shows you how to use Plastic SCM from the command line interface” which starts with this note:

Remember, you can always get more info about all the commands using cm help command_name.

Run the cm help objectspec command to learn about the definition of the different object specs supported by Plastic.

I am not alone in the criticism, for instance [WayBack] Improved “cm.exe” command output – General – Plastic SCM Community

the output behavior seems very uneven across different commands:

  • Some commands accept the --xml argument
  • Other commands allow --machinereadable + --fieldseparator
  • Yet other commands only allow --format (or --errorformat)
  • When using --errorformat + --ignorefailed with “add” all ignored errors are not formatted (either with --format or --errorformat). I don’t know if they’re not considered as errors internally but they show up in the output with a localized human readable string, and that’s not very convenient for automated parsing.
  • --silent is not really silent (at least with “add“)

Getting current status: always use cm status --all

Even though cm status --help indicates a plain cm status should show changes (full help below the fold; see[WayBack] PlasticSCM cm status does not show changes; use cm status --all for that, even though the help says otherwise. · GitHub):

Examples:

    cm status
    (The command will print the working changeset and also the items that are
    checkedout, added, copied, replaced, deleted and moved.)

    cm status --all
    (The command will print all item types changed in the workspace but not
    the ignored ones.)

in practice it does not, so you have to always run cm status --all: I regard this as undocumented.

Finding objects: cm help objectspec is useless

Starting with the last bit, as it crucially important to allow for querying the various object types (that you for instance need with cm find branches or cm find changesets).

Executing it reveals the output is almost meaningless, as cm help objectspec ends with describing what it intents to describe, but then stops:

Describes how to write object specs.

Usage:
    cm help objectspec
    To get all the information about how to build object specs.

Several Plastic SCM commands expect 'object specs' as input to refer to a
given object (typically a branch, changeset, repository, etc).

This documentation describes the different "specs" available and how to
build them.

Finding changesets

It takes a while go get a feel for how to find stuff. This finds changesets more recent than a certain date, by two people:

find changeset where date > '31-10-2018' and (owner = 'jeroen' or owner = 'edwin')

Finding commands

Any software configuration management tool as a lot fo functionality, usually all executable from the command-line.

I was hoping PlasticSCM was no exception, as parts of the documentation hint that cm is the central piece. It is, but finding how to use that functionality is a nightmare. The best way to get information, is to address @plasticscm in your tweet. Usually either of these accounts will follow-up:

The follow-up often urges to ask by email, or use the forums which have threads full of partial information and have their own shares of configuration management issues:[WayBack] milan on Twitter: “@plasticscm your defunct captcha service prevents me from resetting my password. your customer support site is a forum where I can’t start a new topic because the drop down menu is unresponsive. so I’m getting help here, I hope?.

Back to the first part of the quote:

Remember, you can always get more info about all the commands using cm help command_name.

The quote is about “all commands”, but forgets that cm help command_name does not list commands, as there is another very important command that indeed lists almost all the commands: cm showcommands --all which has a long result quoted in this gist.

The cm help command_name is not about all commands. It is about help for any command having documentation.

Finding where you are

Before going back to the all versus any, lets focus on a key aspect in version control: finding out where you are on the command-line from the perspective of the version control structure.

Of course you are in the current directory on the command-line, but what does the version control system think this is bound to on the version control side?

For Mercurial, this for instance includes hg paths to find the repository and hg branch to find the branch and hg id -i to get the hash of the current commit (changeset) or hg parent to get the full commit information.

For git, you can respectively use git remote -v, git branch (or git rev-parse --abbrev-ref HEAD), and git rev-parse HEAD or git log -1.

So what about PlasticSCM? What branch am I in?

There is the cm status command showing this when your current directory is bound to a PlasticSCM repository:

cs:539@rep:MyRepository@repserver:ssl://plastic.example.org:8088

So you have these parts:

  • Changeset
  • Repository
  • PlasticSCM server

The crucial part missing here is the current branch.

Here you find out that  cm showcommands --all misses at least one command that is in the any list, but is in the all list: cm wi, which is not documented on-line either. It is undocumented because it is considered “legacy”:

There is nothing as permanent as legacy, so that kind of information should be documented on-line too.

Here is the built in help for cm wi in the same :

Show info about workspace selector.
gra
Usage:

    cm wi [wk_path]

Options:

    wk_path             Path of a workspace on the machine.

Remarks:
    The wi command shows the working configuration of a workspace (repository,
    branch, and/or label).

Examples:
    cm wi c:\mywk

One problem: cm wi sometimes does not list your branch at all, despite the PlasticSCM GUI showing it.

Still room for research here…

Finding more documentation

Much of the cm documentation can be found at

There is more on the where search syntax here:

Some thinks (like wildcards in filenames) cannot be queried by cm itself: you have to do post-processing like with findstr: [WayBack] Query changes to files matching name pattern – General – Plastic SCM Community.

You have to use single quotes (') instead of double-quotes (") for the where syntax, despite the first hit for [Archive.isplasticscm find changesets for file – Google Search giving [WayBack] Finding changesets where a file is changed – General – Plastic SCM Community.

Luckily [WayBack] How to obtain al revisions from a file – General – Plastic SCM Community tells the correct syntax.

Ignoring files and directories

Plastic uses an ignore.conf to specify which files and directories should be ignored. I am not sure yet about a similar file hidden_changes.conf.

There is hardly any documentation on the ignore.conf syntax, but there is documentation on the places where it can reside: in the repository itself to apply for all repository users, or on your client system in a central place for any repository, or a specific repository. These links tell more:

 

A few things I found out myself on entries in ignore.conf:

  • they are case sensitive
  • there is no distinction between directory and file names

For Delphi I created a stock version:

__history
__recovery
**/Win32/Debug
**/Win32/Release
*.local
*.identcache
*.stat
*.dcu
*.drc

GUI

The above, together with a lot of smaller gripes (for instance no automated check for updates like most other software development tools I know) sort of made me glad am now mainly using other version control systems. But I still miss the branch explorer in those tools.

Screenshots of vertical versus horizontal branch views from [WayBack]  Gamasutra: Matt Schoen’s Blog – I Gave PlasticSCM a Try


-jeroen

Show info about workspace selector.
Usage:
cm wi [wk_path]
Options:
wk_path Path of a workspace on the machine.
Remarks:
The wi command shows the working configuration of a workspace (repository,
branch, and/or label).
Examples:
cm wi c:\mywk

view raw
cm help wi.txt
hosted with ❤ by GitHub

Essential commands:
Command Short Description
——————————————————————————–
add Add an item to version control.
annotate blame Show the changeset where each line of a
file was last modified and its author.
checkin ci Stores changes in the repository.
checkout co Mark files as ready to modify.
diff Diff files, changesets and labels.
find Run SQL-like queries to find Plastic SCM
objects.
help Get help of a Plastic SCM command.
history hist Display the history of a file or
directory.
issuetracker it Get, update or find the issue status in
the specified issue tracker.
label lb Apply an existing label to a given
changeset.
log Get info of revs in changesets.
makebranch mkbr Create a new branch.
makelabel mklb Create a new label and applies it to a
given changeset.
makeworkspace mkwk Create a new workspace.
merge Merge a branch with another branch.
move mv Move or rename a file or directory.
partial Run commands in a partial workspace.
patch Generates a patch file from a spec or
applies a generated patch to the current
workspace.
remove rm Delete a file or directory from version
control.
replicate Push or pull a branch to another repo.
shelve Shelve the contents of checkouts.
showcommands Show all the available commands.
status Show changes in the workspace.
switch Switch the workspace to a branch, cset,
label or shelve.
undochange unc Undo the changes on a path.
undocheckout unco Undo the checkout on an item.
update upd Update the workspace and download latest
changes.
version Show current client version number.
xlink Create, edit or display info of an
xlink.
Additional commands:
Command Short Description
——————————————————————————–
objectspec Describes how to write object specs.
changelist clist Group pending changes in changelists.
changeset cset Execute advanced operations on
changesets.
changeworkspace cwk Change the workspace location.
codereview cr Create, edit or delete code reviews.
getfile cat Download the content of a given
revision.
getstatus Get the status of an item.
listrepositories lrep List the repositories of a server.
listworkspaces lwk List registered workspaces.
ls dir List the contents of a tree.
makeattribute mkatt Create a new attribute.
query Execute SQL queries. Requires SQL
storage.
removeattribute rmatt Remove an attribute.
removebranch rmbr Remove one or more branches.
removelabel rmlb Remove one or more labels.
removeworkspace rmwk Remove a workspace.
renameattribute rnatt Rename an attribute.
renamebranch rnbr Rename a branch.
renamelabel rnlb Rename a label.
renamerepository rnrep Rename a repository.
renameworkspace rnwk Rename a workspace.
revert Revert an item to a previous rev.
rmattributereal Remove an attribute in an object.
setattribute statt Set an attribute to a given object.
showfindobjects sfo List objects and attributes.
synchronize sync Syncronize with Git.
tube Run commands related to Plastic Tube.
uncounchanged unuc Undo non-changed checked out items.
undelete Undelete an item from a specific
revision.
whoami id Show the current Plastic SCM user.
Administrative commands:
Command Short Description
——————————————————————————–
activateuser au Activate a licensed user.
addrepository addrep Connect an existing repository by adding
its database.
admin Execute administrative commands on the
server.
archive arch Archive data in external storage.
changerevisiontype crt Change an item revision type
(bin/txt).
changetrigger chtr Edit a trigger.
checkconnection Check the connection to a server.
checkdatabase chkdb Check the repositories integrity.
deactivateuser du Deactivate a licensed user.
fast-export fe Export a repository using a fast-export
format.
fast-import fi Import Git fast-export data into a
repository.
iostats Show statistics about the hardware.
licenseinfo li Display license information and license
usage.
listlocks Show locks on a server.
listtriggers ltr Show info of a type of trigger.
listusers lu List users and groups.
makerepository mkrep Create a repository in a server.
maketrigger mktr Create a new trigger in a server.
passwd Change the user password (UP).
removerepository rmrep Remove a repository from a server.
removetrigger rmtr Delete a trigger.
showtriggertypes stt Display available trigger types.
unlock Undo item locks on a lockserver.
Security commands:
Command Short Description
——————————————————————————–
acl Set permissions on an object.
setowner sto Set the owner of an object.
showacl sa Show the ACL of an object.
showowner so Show the owner of an object.
showpermissions sp List the available permissions.
Automation commands:
Command Short Description
——————————————————————————–
branchhistory Show the history of a branch.
checkselectorsyntax Check the syntax of a selector.
crypt Crypt a password.
diffmetrics Show diff metrics between two revs.
fileinfo Retrieve detailed information about the
items in the workspace.
findchanged fc Get a list of changed files. This command
is deprecated and kept just for
backwards
compatibility. Use cm status instead.
findcheckouts fco Get a list of checked out items. This
command is deprecated and kept just
for
backwards compatibility. Use cm
status instead.
findprivate fp Get a list of private items. This command
is deprecated and kept just for
backwards
compatibility. Use cm status instead.
getconfig Obtain configuration info.
getmainbranch
getmergeneededbranches Show branches pending to be merged.
getrevision Load a revision in the workspace.
gettaskbranches Get branches linked with a task.
getworkspacefrompath Get workspace info from a path.
linktask Link a changeset to a task.
location Get the path of cm.
manipulateselector Change the selector to a date.
setselector sts Set a selector to a workspace.
showselector ss Show the workspace selector.
* Executing a command:
cm command_name
* Get usage of a command:
cm command_name –usage
cm command_name -?
* Get help from a command
cm help command_name
cm command_name –help
Learn more about how to use the command line:
https://www.plasticscm.com/documentation/cli/plastic-scm-version-control-cli-guide.shtml
Learn more about cm find:
https://www.plasticscm.com/documentation/cmfind/plastic-scm-version-control-query-system-guide.shtml
Learn more about cm automation:
https://www.plasticscm.com/documentation/cmdrunner/plastic-scm-version-control-cmdrunner-guide.shtml

Show changes in the workspace.
Usage:
cm status [wk_path] [–changelist=name | –changelists] [–cutignored]
[–nochanges] [–noheaders] [–nomergesinfo] [–nostatus]
[–selector] [–short] [–symlink] [–wkconfig]
[–dirwithchanges] [–xml[=output_file]] [–encoding=name]
[–wrp] [–fullpaths | –fp] [search_types]
Options:
wk_path Path of the workspace where the search will be
performed.
–changelist Shows changes in the selected changelist.
–changelists Shows changes grouped in client changelists.
–cutignored Skips the contents of ignored directories.
Requires the –ignored search type.
–nochanges Only prints the loaded changeset.
–noheaders The changes group information will not be printed.
–nomergesinfo The merge info for changes is not printed.
–nostatus Only prints the modified item search result.
–selector Prints the changeset on the repository that should be
loaded. The modified item search will be omitted.
–short Lists only paths that contains changes.
–symlink Applies the operation to the symlink and not to the
target.
–wkconfig Prints the workspace configuration (current branch,
label or changeset where the workspace points to).
–dirwithchanges Shows directories that contain changes inside them
(added, moved, removed items inside).
–xml Prints the output in XML format to the standard output.
It is possible to specify an output file.
–encoding Used with the –xml option, specifies the encoding to
use in the XML output, i.e.: utf-8.
See the MSDN documentation at
http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx
to get the table of supported encodings and its format,
(at the end of the page, in the "Name" column).
–wrp Print workspace root relative paths instead of
current directory relative paths.("–wkrootrelativepaths"
flag does the same).
–fullpaths, –fp Force printing absolute paths, overriding any other path
printing setting.
Search types:
–added Prints added items.
–checkout Prints checkedout items.
–changed Prints changed items.
–copied Prints copied items.
–replaced Prints replaced items.
–deleted Prints deleted items.
–localdeleted Prints locally deleted items.
–moved Prints moved items.
–localmoved Prints locally moved items.
–percentofsimilarity=value Percent of similarity between two files
in order to consider them the same item. Used in the
locally moved search. Its default value is 20%.
–txtsameext Only those text files that have the same extension will
be taken into account by the similarity content matching
process during the moved items search. By default any
text file will be processed.
–binanyext Any binary file will be taken into account by the
similarity content matching process during the moved
items search. By default only those binary files that
have the same extension will be processed.
–private Prints non controlled items.
–ignored Prints ignored items.
–hiddenchanged Prints hidden changed items. (Includes '–changed')
–controlledchanged This modifier substitutes the following options:
'–added' '–checkout' '–copied' '–replaced'
'–deleted' '–moved'.
–all This modifier substitutes the following parameters:
'–controlledchanged' '–changed' '–localdeleted'
'–localmoved' '–private'.
Remarks:
The status command prints the loaded changeset on a workspace and gets
the changed elements inside the workspace.
This command can be used to show the pending changes in a workspace; the
type of changes that can be searched can be modified by using the command
parameters. The default option is '–controlledchanged'; this option will
print controlled items that are changed.
The percent of similarity parameter '–percentofsimilarity' (-p) is used
by the locally moved search to decide if two elements are the same item.
The default value is 20% but it can be adjusted.
It is possible to show workspace changes grouped by client changelists.
The 'default' changelist includes the changes that are not included in
other changelists. That being said, the changes the default changelist
will show depends on the search types flags specified.
Showing changes grouped by changelists requires showing controlled
changes too (items with status = 'added', 'checkout', 'copied',
'replaced', 'deleted' or 'moved'). So, the '–controlledchanged' option
will be automatically enabled when changelists are shown.
The default encoding for XML output is utf-8.
By default, this command will print current directory relative paths,
unless the '–machinereadable' or '–short' flags are specified. If
any of them are specified, the command will print absolute paths.
If '–xml' flag is specified, workspace root relative paths will
be printed (unless the '–fp' flag is also specified, printing
absolute paths instead).
Examples:
cm status
(The command will print the working changeset and also the items that are
checkedout, added, copied, replaced, deleted and moved.)
cm status –all
(The command will print all item types changed in the workspace but not
the ignored ones.)
cm status –added
(The command will only print the working changeset and the added items
inside the workspace.)
cm status c:\workspaceLocation\code\client –added
(The command will only print the working changeset and the added items
under the path specified recursively.)
cm status –changelists –all
cm status –changelist –all
(The command will show all the workspace changes grouped by client
changelists.)
cm status –changelist=pending_to_review
(The command will show the changes on the changelist named
'pending_to_review'.)
cm status –changelist=default –private
(The command will show the changes in the 'default' changelist,
showing private items, along with items with controlled changes, if any.)
cm status –short –changelist=pending_to_review | cm checkin –
(The command will check-in the changes in the changelist
'pending_to_review'.)
cm status C:\workspaceLocation –xml=output.xml
(Gets the status information in XML format and using utf-8 in the file
output.xml.)
cm status –ignored
(This command will show all ignored items)
Output:
IG src
IG src/version.c
IG out/app.exe
cm status –ignored –cutignored
(This command will show ignored files whose parent directory is not ignored
and ignored directories -but not their contents)
Output:
IG src
IG out/app.exe

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

 
%d bloggers like this: