PULL
Description
Pulls a branch from another repo.
Usage
cm pull <src_br_spec> <dst_rep_spec> [--preview] [--nodata] [TranslateOptions] [--user=<usr_name> [--password=<pwd>] | AuthOptions]
(Direct server-to-server replication. Pulls a branch from a repository.)
cm pull <dst_rep_spec> --package=<pack_file> [AuthOptions]
(Package based replication. Imports the package in the destination repository.)
cm pull hydrate <dst_br_spec> [<src_rep_spec>] [--user=<usr_name> [--password=<pwd>] | AuthOptions]
(Introduces the missing data for all the changesets of a branch previously replicated with '--nodata'. If a repo to obtain the data is not specified, Unity VCS tries to use the "replication source" (origin of the replicated branch)).
cm pull hydrate <dst_cs_spec> [<src_rep_spec>] [--user=<usr_name> [--password=<pwd>] | AuthOptions]
(Introduces the missing data for a changeset previously replicated with '--nodata'. If a repo to obtain the data is not specified, Unity VCS tries to use the "replication source").
Options
| Option / Argument | Description |
|---|---|
| --preview | Gives information about what changes will be pulled but no changes are actually performed. This option is useful to check the data that will be transferred before replicating changes. |
| --nodata | Replicates the branch changes without replicating the data. This option is not allowed with package replication. |
| --user, --password | Credentials to use if the authentication mode is different in source and destination and there is not a profile to authenticate to destination. |
| --package | Specifies the previously created package file to import for package based replication. Useful to move data between servers when there is no direct network connection. Refer to 'cm push' to create a package file. |
| src_br_spec | The branch to pull from a remote repository. (Use 'cm help objectspec' to learn more about branch specs.) |
| dst_br_spec | The branch to hydrate. (Use 'cm help objectspec' to learn more about branch specs.) |
| dst_cs_spec | The changeset to hydrate. (Use 'cm help objectspec' to learn more about changeset specs.) |
| dst_rep_spec | The destination repository. (Use 'cm help objectspec' to learn more about repository specs.) |
| TranslateOptions | See the Translate options section for more information. |
| AuthOptions | See the Authentication options section for more information. |
Translate options
Mode
--trmode=(copy|name|table --trtable=<translation_table_file>)
The source and destination repositories may use different authentication modes. The '--trmode' option specifies how to translate the user names from the source to the destination. The '--trmode' must be one of the following values:
| Option / Argument | Description |
|---|---|
| copy | (Default). Means that the user identifiers will be just copied. |
| name | The user identifiers will be matched by name. |
| table | Uses a translation table specified in the option '--trtable' (see below). |
Specifics if mode is set to "table"
--trtable=<translation_table_file>
If the translation mode is 'table', a translation table is a file containing lines in the form <oldname;newname> (one per line). When the branch is written to the destination repository, the objects created by a user identified by "oldname" in the source repository will be set to the user with "newname" on the destination.
Authentication options
Authentication data can be specified using one of the two following modes
- Using authentication parameters.
- Using an authentication file.
Using authentication parameters
--authmode=<mode> --authdata=<data>
Where --authmode can take one of the following values
- NameWorkingMode
- LDAPWorkingMode
- ADWorkingMode
- UPWorkingMode
Examples
| Option / Argument | Description |
|---|---|
| (LDAPWorkingMode) | --authdata=::0:dave:fPBea2rPsQaagEW3pKNveA |
| (UPWorkingMode) | --authdata=dave:fPBea2rPsQaagEW3pKNveA== |
The '--authdata' line is the content of the <SecurityConfig> entry in the client.conf file and the profiles.conf file. The profiles.conf file can be easily generated from the Unity VCS GUI in the replication profiles tab under Preferences.
If you are using UPWorkingMode, you can simply specify
--authmode=UPWorkingMode --user=<user> --password=<psw>
Using an authentication file
It's possible to have a different file for each server you connect to, with the credentials for that server and --authfile=<authentication_file> where the authentication_file must be formed by the following 2 lines:
- mode, as described in '--authmode'
- authentication data, as described in '--authdata'
Help
Remarks
The 'pull' command is able to replicate branches (along with their changesets) between a source repository and a destination repository. The repositories can be located at different servers.
There are two replication operations: 'push' and 'pull'.
A 'pull' operation means that the replication operation will demand data from the source repository to be stored into the destination repository. The client will connect to the destination repository and, from that host, it will establish a connection to the source repository to retrieve the targeted data. During pull it is the destination server which will be connected to the source.
Although in a typical distributed scenario a developer pushes data from his local server to the main server, the developer might want to pull the latest repository updates from the main server, too.
Replication can resolve situations where concurrent changes have been made on the same branch on two replicated repositories:
- Push: If you try to push your data to a repository having newer changes than those you are sending, the system will ask you to pull the latest changes, resolve the merge operation and, finally, try to push again.
- Pull: Whenever you pull changesets from a remote branch, they will be correctly linked to their parent changesets. If the changeset you pulled is not a child of the last changeset in the branch, then a multi-headed scenario will appear. The branch will have more than one 'head', or last changeset on the branch. You will need to merge the two 'heads' before being able to push again.
Pull can work in two modes
- Direct communication between servers: The destination server will fetch the data from the source server, automatically synchronizing data for the specified branch. It requires the user running the command to be authenticated by the remote server, either using the default authentication in the client.conf file, or specifiying the '--authmode' and '--authdata' modifiers, or '--authmode' and '--user' and '--password' if the authentication mode is UPWorkingMode.
- Import a previously generated package with push and the '--package' option. This mode requires using a package file previously generated with the push command.
Keep in mind that pull replication works in an indirect way. When executed, the command asks the destination repository to connect to the source and obtain the selected branch.
However, this can be done directly by using the push command. This will make the command replicate the selected branch from source to destination.
Examples
cm pull br:/main@project1@remoteserver:8084 projectx@myserver:8084
(Pulls the 'main' branch from 'remoteserver' to 'myserver'. In this case, both servers are configured with the same authentication mode.)
cm pull br:/main@project1@remoteserver:8084 projectx@myserver:8084 --authmode=LDAPWorkingMode --authdata=::0:dave:fPBea2rPsQaagEW3pKNveA
(Pulls the same branch as before, but now the remote server is configured to authenticate users with Active Directory. For instance, I am connecting from a Linux machine to a Windows server configured to use Active Directory integrated mode. I will specify my Active Directory user and cyphered password and pass it as LDAP to the server.)
cm pull br:/main@project1@remoteserver:8084 projectx@myserver:8084 --authmode=UPWorkingMode --user=dave --password=mysecret
(Pulls the same branch, but now users are authenticated on the remote server, taking advantage of the user/password database included in Unity VCS.)
cm pull br:/main@project1@remoteserver:8084 projectx@myserver:8084 --nodata
(Replicates the 'main' branch from 'remoteserver' to 'myserver' without data.)
cm pull hydrate br:/main@projectx@myserver:8084 projectx@remoteserver:8084
(Hydrates all the changesets in the 'main' branch obtaining the data from the remote server.)
cm pull hydrate cs:122169@projectx@myserver:8084 projectx@remoteserver:8084
(Hydrates changeset 122169 in 'myserver' obtaining the data from the remote server.)