Downloading the CLI
The SCM CLI is available from jazz.net downloads page under the "Rational Team Concert," which is the bug tracking and source control portion of JazzHub. You use the same credentials here as you use for JazzHub. From there you can pick a release (preferably the latest) and go to the "All Downloads" section.You can go back periodically to get new versions of the CLI. JazzHub is compatible with the latest release of Rational Team Concert but not the milestone releases (M1, M2, RC1, ...). If you don't want to upgrade you can generally use the CLI from previous RTC releases with JazzHub.
Installing on Ubuntu Linux
The installation steps depend on what operating system you are using. For example, if you are using Ubuntu Linux then you can use "Ubuntu Linux package for SCM Tools" from the downloads page. Unzip it and then install using the "dpkg" tool like this:$ sudo dpkg -i scmtools_x.x.x.deb
If you are using a 64-bit system or you would like more details check out this article.
Installing on Windows / Red Hat Linux / SUSE Linux
Download the "Client for Eclipse 3.6.x IDE" for Linux from the downloads page above. The CLI is bundled with the Eclipse IDE. You don't have to use the IDE if you don't want it.Unzip it and add the "jazz/scmtools/eclipse" directory to your path. For example, if you are on Windows you can add to the path using the Control Panel \ System Settings \ Advanced Settings \ Environment Variables dialog by adding ";C:\path-to-unzipped-folder\jazz\scmtools\eclipse" to the end of the PATH variable.
Otherwise, you can add something like the following line to your /home/cmcgee/.bashrc file on Red Hat or SUSE:
export PATH=$PATH:/home/cmcgee/jazz/scmtools/eclipse
After you change the system path you can restart your terminal or command prompt and run the "scm help" command to verify that the installation is correct. It should provide a list of the available CLI commands.
Installing on Mac OS X
In the "SCM Tools" section download the Mac OS X edition. Unzip it and add an entry like the following to your /Users/Chris/.bash_profile file:export PATH=$PATH:/Users/Chris/jazz/scmtools/eclipse
Restart your terminal and run the "scm help" command to verify that the installation is working. Java is needed for the CLI but it is an optional install on Mac OS X. If it is not installed you should be prompted to install it when running the help command.
Registering file types
Although, the SCM CLI understands a number of common source code file types (e.g. C/C++, Java, Javascript, HTML, C#, Python and Go among others) it doesn't have a complete list. If it doesn't understand a particular file type it will treat it as a binary file. This may not be a problem for you. However, the CLI does not automatically convert the line terminator characters from Windows to Unix style (and vice versa) for binary files. Also, the CLI will not attempt to automatically resolve merge conflicts in the file contents when the file is binary.If your project contains source code with file types that are unlikely to be known to the CLI and you are concerned about the line terminators and auto-merge behaviour then you can tell it about them using a "magic" file. First, create a file called "magic.properties" in either ".jazz-scm" in your home directory on Linux/Mac or in your user profile directory (usually something like /Users/Chris) on Windows. In that file you can create lines that look like this for each of your different file types:
*.groovy: mime: text/plain; delim: platform
Everyone on your team should add the same entries to their own magic file.
Logging in
Now that the CLI is installed you can begin working with your JazzHub project's source code. Many of the CLI commands need to connect to a repository. Each JazzHub project is assigned to a repository with a URL (e.g. https://hub.jazz.net/ccm01). You can find your the URL in the bottom right of your JazzHub project page when you click the "here's how to get setup" link.Repository URL's are long and when combined with your user ID and password make for alot of typing for each CLI command. Luckily there is a way to cache your credentials and create a nick name for the repository using the login command. This command will log in to the https://hub.jazz.net/ccm01 repository giving it a nick name of "jazzhub01":
$ lscm login -r https://hub.jazz.net/ccm01 -u userid -c -n jazzhub01
You are prompted for your JazzHub password and all of this information is cached using the nick name "jazzhub01." When you invoke CLI commands that require a repository you can use just the nick name for the "-r" parameter and save the extra typing.
Creating your repository workspace
Unlike some other SCM systems much of your day-to-day work is normally kept in your own workspace on the server (ie. repository). Even if you are not ready to share your changes with others you are able to organize them right away into change sets. It's good to keep the changes safely stored in the repository to avoid accidental data loss due to accidental deletion or even hard drive failure.Repository workspaces hold your own changes but streams are where changes are shared with the rest of the team. To create your repository workspace run the create workspace command to create one named "myuserid-workspace1" to "flow" with your project's stream named "userid | projectname":
$ lscm create workspace -s "userid | projectname" -r jazzhub01 myuserid-workspace1
Each JazzHub project is given a name of the form "userid | projectname" with the userid of the initial creator. This is the name assigned to the project's stream. Also, notice the "-r" parameter with the nick name we created in the last section. Many of the CLI command use this parameter to refer to a repository URL or its nick name.
Sharing your code
If you are working with an established project you can skip this section. When a JazzHub project is new then your first step will be to share the source code you have on your hard disk safely into your repository workspace. Change directory (ie. cd) into the top-level folder of your source code and execute the share command:$ lscm share -r jazzhub01 myuserid-workspace1 folderWithCode "userid | projectname Default Component"
The workspace name matches the one you used to create it in the previous section. Change "folderWithCode" to the name of the folder you want to share. The last parameter should match your project name with the "Default Component" suffix. Components are a more advanced SCM topic that doesn't need to be covered for our purposes here.
At this point your source code is backed up in your repository workspace but it is not yet visible to the rest of your team. You need to flow, or deliver, the change set to the project stream so that other people can see it.
$ lscm deliver
Loading your repository workspace
If you just finished sharing your code then you can skip this section. When you want to work on an existing JazzHub project you will need to download (ie. load) the contents of your repository workspace on to your hard drive so that you can begin working with it. Create an empty folder on your hard drive, change directory (ie. cd) into it and run the load command.$ lscm load -r jazzhub01 myuserid-workspace1
This command can take time to transfer all of the files, especially for larger projects. Notice that the repository workspace name is the one you used above to create it. The nick name makes the load command nice and terse.
Working day-to-day
It's a good idea to check your changes in frequently. It can help to back up your work in case of disaster. Also, you can organize your changes right away into change sets. You can use the checkin command like this:$ lscm checkin path/to/file.txt
The checkin command will automatically create a new change set if necessary and add the change to it. If you want to use more than one change set at a time to organize your changes (e.g. for unit tests) you can use the create changeset command.
$ lscm create changeset
Commands that work with change sets will show the change set ID, which is rendered as a four digit number in round brackets (e.g. "(1024)"). You use the change set ID with the checkin command to place the change into that change set.
$ lscm checkin -c 1024 path/to/file.txt
If you forget what change sets are active in your repository workspace or you want to see what files you have changed that are not checked in you can use the "lscm show status" command. The status information will also show the change set comments and work items. These bits of contextual information can be very helpful down the road. It is good practice to assign a comment and/or associate a JazzHub work item using its number.
$ lscm set changeset --comment "Unit Tests for feature xyz" 1025 $ lscm add workitem 1025 6524Deliver all of your change sets to the stream with the deliver command. If you want to deliver specific change set(s) you can provide the change set ID's.
$ lscm deliver 1024 1025
Other members of the team will periodically deliver their change sets to the project stream. You can keep track of these new change sets using the "lscm show status" command observing the "Incoming" section. You can flow, or accept, all of the incoming change sets into your repository workspace using the accept command.
$ lscm accept
Once the accept command is complete the changes that you have accepted will show up immediately on your hard disk.
Next steps
The nick name has already saved a significant amount of typing so far. Some of the CLI commands have aliases to make them even more concise. For instance, you can replace the term "changeset" with "cs" in any of the commands shown above. Workitem can be shortened to "wi." Likewise, "checkin" is easily shortened to "ci." Command aliases can be found in the command's help (e.g. "lscm help create changeset").One really useful SCM pattern is to organize your production code changes and unit test changes into separate change sets. As you are iterating on each set of changes you can temporarily suspend the production change set to validate that they fail without the production changes. When you resume them the tests should pass. You can do this with the suspend and resume commands, or "susp" and "res" if you prefer to save the extra keystrokes.
When you accept change sets from the team's stream you will occasionally run into conflicts. If files are marked as registered as text (see above section) and the content changes occur in different parts of the file the CLI will attempt to automatically resolve the conflict by applying both changes to your file. If changes cannot be automatically merged then you will need to merge in the changes yourself. Check out the show conflicts command to view the different aspects of a conflict and the resolve conflict command to resolve the conflicts in different ways (mine, proposed).
Hopefully, this post has provided some guidance on how to get started with your JazzHub project using the SCM CLI. There are a number of articles that cover how to use it in more depth. Another article was written recently about hacking JazzHub projects from the command line from a slightly different perspective.
Comments and feedback are welcome.
