Roundtable Commander

The Roundtable Commander is a simple command line client for Roundtable TSMS providing basic SCM functionality through a simple – platform independent - character user interface.

Install Java Runtime Environment (JRE)

The Roundtable Commander client is a Java application and as such it does require a Java runtime environment to be installed before - the minimum required version is 11. You can download a Java Runtime Environment form either Oracle or OpenJDK, no Java Development Kit (JDK) is required.

Install using the installer

The easiest way to install the Roundtable Commander client is to use the platform independent installer (IzPack) which includes, beside the client binary, the documentation in HTML format for the specific version installed - the online documentation always shows the latest version so there might be some differences or missing features compared to the version installed.

The installer will also try to detect the available Java runtime required (JRE 11 or above), however being a Java based installer the Java runtime environment must be already installed on the system.

DownloadJava Installer

Once downloaded the installer can be launched proven there is a Java Runtime Environment (JRE) available on the system.

Select the installation path, where both the binaries and the HTML documentation will be installed - you might want to add this to the "PATH" environment variable afterwards to make it easier to run the Roundtable Commander client - "rtb".

As the last step the installer will create an "uninstall" script, into the same installation path, that can be later used to uninstall the Roundtable Commander client.

Platform specific artefacts

Alternatively platform specific artefacts can be downloaded directly, please note those doesn't include any documentation and Java Runtime Environment is still needed.

Windows

Unix/macOS

For Windows the download contains only the client executable - "rtb.exe" - with the Java library bundled inside, while the Unix tarball - "rtb-commander.tar.gz" includes both the Java library in a separate "wrapper" folder and a shell script - "rtb" that is used to launch the client (you might need to set the executable permission on it in order to be able to ran it directly). As with the installer it is recommended to add the installation path to the system PATH environment variable so you don't have to specify the full path when executing the client.

Now that you have the Roundtable Commander client installed is time to learn what it can be used for, there should be a Roundtable TSMS instance to which you have access to otherwise there isn't really anything else to it.

Before we start accessing content from the Roundtable TSMS repository make sure you write down the connection URL - the same URL used in Roundtable client, basically the connection string for the Progress Application Server hosting the Roundtable TSMS repository, as well as the credentials required to connect to it.

1. Clone

The first step, and the most important functionality of the Roundtable Commander, is to download content from a remote Roundtable TSMS repository and make a local copy of it so it can always be accessible even if the Roundtable TSMS server isn't available or when disconnected from the internal network.

Since there is no similar functionality in Roundtable TSMS clients we decided to go with the term "clone" which is the default used in distributed SCM systems.

If you have any prior experience with "git" then you can probably just skip this intro altogether, just note the equivalence between "branch" (git) and "workspace" (Roundtable) and other than that the syntax is pretty much the same (albeit not all functionality is implemented, yet).

When you want to "clone" the content of a Roundtable TSMS repository you have to decide how the clone will be used afterwards and those are the most commons questions to answer upfront:

does the repository contains multiple workspaces
are those related (branches of same product: development, test, production) or not (different products sharing the same repository)
do you need all of those workspaces or just one/several of them
do you need the complete history (this includes all previous versions of each source)
do you need the 'current' content or a specific point in time (release)

Please be aware that downloading a large repository with all commit history can take a considerable amount of time, this is not advisable to be done over the internet/VPN.

When cloning a remote repository you can specify the folder where the local repository will be placed - the folder must not exist or needs to be empty otherwise an error will be raised, it defaults to the current working folder.

The "clone" command is the only command that can be executed from outside of a local repository, all other commands requires that the working folder to be a valid local repository.

You can recognise a local repository by the presence of a '.rtb' folder in it, this is where all the information about remote repositories, existing workspaces including commit history and versions are being stored.

The content of the ".rtb" folder should not be manually tampered with otherwise the local repository structure might became invalid.

1.1 Clone a single workspace

If all you need to work is a single workspace from the Roundtable TSMS repository then the command to use is:

> rtb clone -w <workspace_name> <server_url> <clone_folder>

This will download all sources, including all previous versions and commit history but only for the workspace specified.

If you do not need the complete history but only the current content, or only a limited history, you can use the 'shallow clone' and specify the 'depth' - a value of "1" effectively means no history as it will only download the current content and make it looks like all the changes were done into a single commit.

> rtb clone -w <workspace_name> -d 1 <server_url> <clone_folder>

1.2 Clone a specific workspace release

If a specific release of a given workspace from the Roundtable TSMS repository is needed then the command to use is:

> rtb clone -w <workspace_name> -r <release> <server_url> <clone_folder>

This will download all sources, including all previous versions and commit history for the workspace specified up to the specified release number (using release note instead of the number also works). Make sure you use the "-d" (depth) option if only the current sources of the release are needed and not the whole history up to that point.

1.3 Clone all workspaces

If you really need to download all workspaces from the Roundtable TSMS repository then the command to use is:

> rtb clone -a [-h <workspace_name>] <server_url> <clone_folder>

This will download all sources, including all previous versions and commit history for all workspaces from the repository - it could potentially take some time to complete based on the size of the repository. You can specify which of those workspaces to be used as initial workspace - the one that will be check-out during clone - using the "-h" command option, it defaults to the first workspace from the remote repository.

Same as for single workspace download you can limit the size of history entries by using the "-d" (depth) command option - this will be used for all workspaces.

2. Remotes

The Roundtable Commander supports sources from multiple remote Roundtable TSMS repositories to be downloaded into the same local repository - it doesn't necessarily need to be setup as 'partner sites' but this could be one use-case.

Unless otherwise specified, during the "clone" operation the initial remote repository is named "origin" - you can specify a different name using the "-o" option for the "clone" command.

To see the list of remotes registered for the local repository you can use the "remote" command with the "list" option.

> rtb remote list -v

It is possible to add/update/remove remotes using the other sub commands of the "remote" command, consult the documentation or use the inline help command for more details.

> rtb remote --help

3. Checkout

If multiple workspaces were downloaded from the remote Roundtable TSMS repository (multiple repositories are also supported) one can switch from one workspace to another by using the "checkout" command - this is again a term commonly used in distributed SCM.

To better understand the checkout concept it might help to know that the 'local repository' obtained after a 'clone' operation contains two types of 'workspaces':

remote-tracking workspace - is a 'read-only' image of the workspace cloned from the Roundtable TSMS
local workspace - is an editable workspace where local changes can potentially be performed (not implemented yet), it might be linked to a remote-tracking workspace

The "checkout" operation switch from one local workspace to another with one twist, when trying to switch to a local workspace that does not exist but there is one remote-tracking workspace in only one "remote" then a local workspace is created from and linked to the remote-tracking one.

As an example say that all workspaces were downloaded from a remote repository using "clone" and the repository had two workspaces: "devel" and "prod" with the first one being used as initial workspace.

> rtb clone -a -h devel server_url myapp

Now the "myapp" folder will contain a local repository with two remote-tracking workspaces ("devel" and "prod") and one local workspace ("devel").

The local repository folder - myapp - will contain the sources of the "devel" workspace, if you want to see the sources of "prod" workspace you need to checkout that workspace instead.

> rtb checkout prod

Although the local workspace "prod" was not present one was created from the remote-tracking workspace with the same name and it's content was checked-out. The content of the local repository folder will be replaced with the sources from the "prod" workspace. This doesn't mean the content of previous workspace ("devel") was lost or anything, you can switch back to it at any time using the "checkout" command.

Make sure you remember to switch the working folder to the remote repository "myapp" folder before executing the command.

3.1 Checkout a specific release

If the commit history is available and you need to see the workspace content as it was at a specific point in time when a particular release was created you can do so by specifying the release number by appending it to the workspace name with the '@' prefix.

> rtb checkout prod@1.2.3

This will place the content of the "prod" workspace as it was when the release "1.2.3" was created inside the local repository folder - the current workspace is now in a "detached" mode (read-only).

4. Fetch/Pull

The content of workspaces from a local repository won't be updated automatically when changed on the Roundtable TSMS repository so you won't be able to see those changes unless 'pulled' down from the server.

The terms used by distributed SCM systems are 'fetch' and 'pull', the only difference between the two being that 'fetch' is only updating the remote-tracking workspaces into the local repository with content from the remote Roundtable TSMS repository, while the 'pull' is doing the same thing plus it updates the currently checked-out local workspace.

Because the remote-tracking workspaces are read-only those can be updated automatically and it can be done all at once with a 'fetch' or 'pull', however local workspaces must be update one by one using the 'pull' command after setting the current workspace using 'checkout' as needed.

There are multiple options that can be used for 'fetch' and 'pull' based on your needs, by default it just update the remote-tracking workspace attached to the current workspace (if any) and also update the content of local workspace for 'pull'.

The "reference" used for fetch/pull can be one of those:

local workspace - it will update the remote-tracking workspace linked to it
remote-tracking workspace - update the remote-tracking workspace or download it from the remote repository if not downloaded before
remote repository - by defaults update all remote-tracking workspaces from the remote repository, there are options to also download the ones missing from local repository or prune the ones that does not exist on the remote repository anymore

4.1 Update one workspace

If you specify a local workspace as a reference, it's remote-tracking workspace is being updated but local workspace remains untouched - you can afterwards compare the two to see what was changed in between.

> rtb fetch devel

Now the remote-tracking "devel" workspace will have it's content up to date with the content from remote repository, in order to update the content of local workspace you need to use the "pull" command instead.

4.2 Update one remote-tracking workspace

If you specify a remote-tracking workspace as a reference this one will be updated if already present - downloaded during "clone" or previous "fetch" - or downloaded fresh if it exists on the remote repository.

> rtb fetch remotes/origin/devel

This will update the remote-tracking "devel" workspace by fetching all new changes done on the remote repository since the initial "clone" - it is not a complete download, only new commit history entries and source versions are being downloaded.

> rtb fetch remotes/origin/unittest

This will create a new remote-tracking "unittest" workspace by fetching all commit history entries and source versions, the "-d" (depth) option can be used to control the level of history entries to be downloaded much like for the "clone" operation.

4.3 Update workspaces from a remote

If you specify the remote repository as a reference only the 'known' remote-tracking repositories are being updated - those already fetched previously either by the initial "clone" or additional "fetch" operations.

> rtb fetch origin

Now the two known remote-tracking workspaces ("devel" and "prod") will be updated.

> rtb fetch origin --missing

Beside updating the two known remote-tracking workspaces ("devel" and "prod") this will also download the missing remote-tracking workspace "unittest".

5. Diff

Another interesting feature made possible when all the information is downloaded locally is to see what are the differences between different workspaces or even between releases of specific workspaces.

The "diff" comand can take up to two parameters to specify the two sides of the comparison - if only one parameter is used the baseline is considered to be the currently check-out workspace.

5.1 Compare current workspace with another branch

To check what differences are between the currently checked-out workspace - say "devel" - and another workspace, "prod" you can use the following command:

> rtb diff prod

5.2 Compare two workspaces with each others

To check what differences are between two workspaces - say "prod" and "unittest" you can use the following command:

> rtb diff prod unittest

5.3 Compare two releases

To check what differences are between two releases (normally of the same workspace but it can also be from different workspaces) - say release "12.4.2" and "12.5.2" of the "corelib" workspace you can use the following command:

> rtb diff corelib@12.4.2 corelib@12.5.2

5.4 Compare local with remote-tracking workspace

Keep in mind there is a difference between the local branch and the originating remote-tracking branch - that could have been updated using the "fetch" command - to see the differences between them the command could look like this:

> rtb diff prod remotes/origin/prod