Clone command

The Clone command is the first step in setting up a local Git repository for further Push and Pull commands with StarTeam.

In this topic:

Using the Clone command

The Clone command clones a view from a StarTeam view into a newly created directory. It creates remote-tracking branches for each child view (branch) in the cloned repository (visible using git branch -r ), creates an initial branch that is forked from the main StarTeam view, and checks it out.

The first user who clones from a StarTeam view establishes a clone time and checks out all files from the view based on the clone time. The first Clone operation does not fetch any history prior to the clone time, into the git repository. Existing child views will not be fetched as branches.

Future Clone operations however, will fetch history from the StarTeam view since the clone time also creates branches in Git corresponding to child views created since the original clone time.

After the Clone, use a git fetch command without arguments to update all the remote-tracking branches, and a git pull without arguments to also merge the remote master branch into the current master branch, if one exits. All StarTeam change packages created since the last pull/fetch will be fetched as a Git commit.

The following is the syntax of the StarTeam connection URL: (Entries within [] are optional)

starteam://[username:password@]<hostname>:<port>/<project name>[/<view name>][/<folder path>]

Back to top

Partial cloning

The StarTeam GIT client also supports cloning partial history using the –depth option in the GIT clone command. For example,

creates a shallow clone of history 3 levels. If there are branches that were created before the depth, they will be ignored. Note that the branch picker dialog is not shown when the depth option is specified, and only branches within the depth level will be cloned.

By default, when using git clone with the depth option, it does not clone branches (see https://git-scm.com/docs/git-clone). To fetch branches, add the –no-single-branch option to the string.

Example 1: Cloning the Full View Hierarchy

This example illustrates the cloning of a new Git repository where:

• Project = SampleProject
• View = SampleView
• Server = 10.150.1.12
• Port = 49201
• Working Directory = C:\gitdemo\Sample

C:\gitdemo\Sample> git clone Administrator:Administrator@10.150.1.12:49201/SampleProject/SampleView  

The above command clones a new Git repository in the current working folder and checks out the files from 'SampleView' to disk. Note that the username/password can be optionally passed in the command line. Recommended way is to use the Git credential manager to store the credentials on Windows.

The following is an example for specifying a full view hierarchy.

C:\gitdemo\Sample>git clone "10.150.1.12:49201/SampleProject/SampleView:1.x Release:1.2 Release"

Back to top

Example 2: Cloning from a subfolder

C:\gitdemo\Sample>git clone "10.150.1.12:49201/SampleProject/SampleView/src/core/java”

While cloning from a sub folder, branches are not cloned. The clone command is performed on the view configuration as of current time and not of the 'clone time'.

Back to top

Example 3: Cloning from root view of a project

C:\gitdemo\Sample>git clone "10.150.1.12:49201/SampleProject”

When a shortened form of URL without a view name in it is passed, the clone command clones from the root (default) view of the project.

Back to top

Example 4: Branch support

When a user clones from a StarTeam view, child views of the main view created after the established 'clone time' are cloned as branches in Git repository. Note that only accessible derived views of Branch-all Variant view type are supported to be cloned as branches. Other types of views like Reference views, Non-derived views and Branch-none variant views are not considered for branching.

Let's take an example of a StarTeam View hierarchy

Demo

• 1.0
• 2.0
• 3.0
• Sandbox

Assuming that the child views (1.0, 2.0, 3.0, Sandbox) were created after the 'clone time', the following command clones the main view of the Demo project along with its child views

C:\gitdemo\Sample>git clone "localhost:49201/Demo/Demo” 

A dialog box is shown where the user can select the branches to be cloned along with the main view. All immediate child views are available by default for branching.

Any child views excluded by the user would mean that subsequent pulls/push commands would ignore that view too.

The above clone command would fetch all the child views as branches and checkout from the master branch (view). The branches be verified using the following git branch command.

C:\gitdemo\Sample > git branch -a

* master
  remotes/origin/1.0_Release
  remotes/origin/HEAD -> origin/master
  remotes/origin/2.0_Release
  remotes/origin/3.0_Release
  remotes/origin/Sandbox
  remotes/origin/master

As the command output shows, clone command successfully created remote tracking branches for each valid child view.

To checkout to a specific branch, run the following command:

C:\gitdemo\Sample > git checkout 2.0_Release

The checked out content should map exactly with the '2.0 Release' view in StarTeam.

Note the difference between the child view names in StarTeam and the Git branch ref name. In Git ref names for branches follow certain naming conventions . It is important that StarTeam view names are normalized accordingly. All special characters in the StarTeam view names are replaced by hyphens ('-') and blanks are replaced by underscores ('_'). Leading and trailing slashes, dots, hyphens, and underscores are also removed.

If the user is running in a command line mode and wants to disable the branch selection pop-up dialog , the Git clone command should be run with a configuration option (git-st.server.noprompt) set as follows:

C:\gitdemo\Sample>git clone "starteam://localhost:49201/Demo”  -c “git-st.server.noprompt=true”

The above command would check out all valid views as branches by default to the Git repository.

To check out just the master branch use the –single-branch option:

 C:\gitdemo\Sample>git clone "starteam://localhost:49201/Demo” -c “gitst.
server.noprompt=true” –single-branch

To exclude certain branches during clone use the git config option excludeBranches as shown below:

C:\gitdemo\Sample>git clone "starteam://localhost:49201/Demo” -c “gitst.
server.noprompt=true” --config "git-st.server.excludedBranches=1.0,2.0" 

Git clone/pull/push from/to StarTeam projects work against multiple levels of StarTeam views. Previously, only immediate child views were fetched/cloned as git branches.

Git clone must fetch all relevant StarTeam views (from multiple levels) as git branches by default. Branch picker dialog is still provided to select branches.

Note that Git branch names are unique. Thus, StarTeam view names in the view hierarchy must all be unique. If there are duplicate view names, an error occurs when trying to clone/pull/push from a StarTeam project. The reported view names must be fixed to be unique in the hierarchy for the git commands to succeed.

Back to top

Supported Git clone command options

The following are some of the supported Git clone options with the StarTeam Git Client:

--no-checkout(-n)

--bare

--origin (-o)

--branch (-b)

--no-tags

--[no-]single-branch

--separate-git-dir=<git dir>

Back to top

Unsupported options

--depth <depth>

--shallow-since=<date>	

--shallow-exclude=<revision> 

--recurse-submodules[=<pathspec]  

--[no-]shallow-submodules  

--jobs <n>