This will delete the page "GIN CLI Help". Please be certain.
GIN detailed command overview
This page describes the purpose and usage of each command of the GIN command line client by elaborating on its Usage, Description, and Arguments.
The same information can be obtained from the client with the commands
gin help
gin help <command>
Login to the GIN services
gin login [<username>]
Description
Login to the GIN services.
If no username is specified on the command line, you will be prompted for it. The login command always prompts for a password.
Flags
--server: Specify server alias to log into. See also 'gin servers'.
Logout of the GIN services
gin logout
Logout of the GIN services.
This command takes no arguments.
Flags
--server: Specify server alias where the repository will be created. See also 'gin servers'.
Create a new repository on the GIN server
gin create [--here | --no-clone] [<repository>] [<description>]
Description
Create a new repository on the GIN server and optionally clone it locally or initialise working directory.
Arguments
<name>The name of the repository. If none is provided, you will be prompted for one. If you want to provide a description, you need to provide a repository name on the command line first and the description second. Names should contain only alphanumberic characters, '.', '-', and '_'.
<description>A repository description (optional). The description should be specified as a single argument. For most shells, this means the description should be in quotes.
Flags
--here: Create the local repository clone in the current working directory. Cannot be used with --no-clone.--no-clone: Create repository on the server but do not clone it locally. Cannot be used with --here.--server: Specify server alias where the repository will be created. See also 'gin servers'.
Examples
Create a repository. Prompt for name
$ gin create
Create a repository named 'example' with no description
$ gin create example
Create a repository named 'mydata' and initialise the current working directory as the local clone
$ gin create --here mydata
Create a repository named 'eegdata' with a description
$ gin create eegdata "My repository for storing EEG data"
Initialise the current directory as a gin repository
gin init
Description
Initialise a local repository in the current directory with the default options.
Retrieve (clone) a repository from the remote server
gin get [--json] <repopath>
Description
Download a remote repository to a new directory and initialise the directory with the default options. The local directory is referred to as the 'clone' of the repository.
Arguments
<repopath>The repository path must be specified on the command line. A repository path is the owner's username, followed by a "/" and the repository name.
Flags
--json: Print output in JSON format.--server: Specify server alias for the repository. See also 'gin servers'.
Examples
Get and initialise the repository named 'example' owned by user 'alice'
$ gin get alice/example
Get and initialise the repository named 'eegdata' owned by user 'peter'
$ gin get peter/eegdata
Download all new information from a remote repository
gin download [--json] [--content]
Description
Downloads changes from the remote repository to the local clone. This will create new files that were added remotely, delete files that were removed, and update files that were changed.
Optionally downloads the content of all files in the repository. If 'content' is not specified, new files will be empty placeholders. Content of individual files can later be retrieved using the 'get content' command.
Flags
--content: Download the content for all files in the repository.--json: Print output in JSON format.
Upload local changes to a remote repository
gin upload [--json] [--to <remote>] [<filenames>]...
Description
Upload changes made in a local repository clone to the remote repository on the GIN server. This command must be called from within the local repository clone. Specific files or directories may be specified. All changes made will be sent to the server, including addition of new files, modifications and renaming of existing files, and file deletions.
You can specify which remotes the content will be uploaded to using the --to flag. The flag can be specified multiple times. If the keyword 'all' is specified as a remote, the data is uploaded to all configured remotes.
If no arguments are specified, only changes to files already being tracked are uploaded.
Arguments
<filenames>One or more directories or files to upload and update.
Flags
--json: Print output in JSON format.--to: Upload to specific remote. Supports multiple remotes, either by specifying multiple times or as a comma separated list (see Examples). If the keyword 'all' is specified, the data is uploaded to all configured remotes.
Examples
Upload 'data1.dat' and 'values.csv' to default remote
$ gin upload data1.dat values.csv
Upload all files in current directory to default remote
$ gin upload .
Upload all previously committed changes to remote named 'labdata'
$ gin upload --to labdata
Upload all '.zip' files to remotes named 'gin' and 'labdata'
$ gin upload --to gin --to labdata *.zip
or
$ gin upload --to gin,labdata *.zip
List the sync status of files in the local repository
gin ls [--json | --short | -s] [<filenames>]...
Description
List one or more files or the contents of directories and the status of the files within it. With no arguments, lists the status of the files under the current directory. Directory listings are performed recursively.
In the short form, the meaning of the status abbreviations is as follows: OK: The file is part of the GIN repository and its contents are synchronised with the server. TC: The file has been locked or unlocked and the change has not been recorded yet (and it is unmodified). NC: The local file is a placeholder and its contents have not been downloaded. MD: The file has been modified locally and the changes have not been recorded yet. LC: The file has been modified locally, the changes have been recorded but they haven't been uploaded. RM: The file has been removed from the repository. ??: The file is not under repository control.
Arguments
<filenames>One or more directories or files to list.
Flags
--json: Print listing in JSON format (uses short form abbreviations).--short: Print listing in short form.
Download the content of files from a remote repository
gin get-content [--json] [<filenames>]...
Description
Download the content of the listed files. The get-content command is intended to be used to retrieve the content of placeholder files in a local repository. This command must be called from within the local repository clone. With no arguments, downloads the content for all files under the working directory, recursively.
Arguments
<filenames>One or more directories or files to download.
Flags
--json: Print output in JSON format.
Remove the content of local files that have already been uploaded
gin remove-content [--json] [<filenames>]...
Description
Remove the content of local files. This command will not remove the content of files that have not been already uploaded to a remote repository, even if the user specifies such files explicitly. Removed content can be retrieved from the server by using the 'get-content' command. With no arguments, removes the content of all files under the current working directory, as long as they have been safely uploaded to a remote repository.
Note that after removal, placeholder files will remain in the local repository. These files appear as 'No Content' when running the 'gin ls' command.
Arguments
<filenames>One or more directories or files to remove.
Flags
--json: Print output in JSON format.
Lock files
gin lock [--json] <filenames>...
Description
Lock one or more files to prevent editing. This changes the type of the file in the repository. A 'commit' command is required to save the change. Locked files that have not yet been committed are marked as 'Lock status changed' (short TC) in the output of the 'ls' command.
Locked files are replaced by pointer files in the working directory (or symbolic links where supported by the filesystem).
Locking a file takes longer depending on the size of the file.
Arguments
<filenames>One or more directories or files to lock.
Flags
--json: Print output in JSON format.
Unlock files for editing
gin unlock [--json] <filenames>...
Description
Unlock one or more files to allow editing. This changes the type of the file in the repository. A 'commit' command is required to save the change. Unmodified unlocked files that have not yet been committed are marked as 'Lock status changed' (short TC) in the output of the 'ls' command.
Unlocking a file takes longer depending on its size.
Arguments
<filenames>One or more directories or files to unlock.
Flags
--json: Print output in JSON format.
Record changes in local repository
gin commit [--json] [--message message] [<filenames>]...
Description
Record changes made in a local repository. This command must be called from within the local repository clone. Specific files or directories may be specified. All changes made to the files and directories that are specified will be recorded, including addition of new files, modifications and renaming of existing files, and file deletions.
If no arguments are specified, no changes are recorded.
Arguments
<filenames>One or more directories or files to commit.
Flags
--json: Print output in JSON format.--message: Commit message
Add a remote to the current repository for uploading and downloading
gin add-remote <name> <location>
Description
Add a remote to the current repository for uploading and downloading. The name of the remote can be any word except the reserved keyword 'all' (reserved for performing uploads to all configured remotes).
The location must be of the form alias:path or server:path. Currently supported aliases are 'gin' for the default configured gin server, and 'dir' for directories. If neither is specified, it is assumed to be the address of a git server. For gin remotes, the path is the location of the repository on the server, in the form user/repositoryname. For directories, it is the path to the storage directory.
When a remote is added, if it does not exist, the client will offer to create it. This is only possible for 'gin' and 'dir' type remotes and any other GIN servers the user has configured.
A new remote is set as the default for uploading if no other remotes are configured. To set any new remote as the default, use the --default option. Use the 'use-remote' command to change the default remote at any time.
Arguments
<name>The name of the new remote
<location>The location of the data store, in the form alias:path or server:path
Flags
--create: Create the remote on the server if it does not already exist.--default: Sets the new remote as the default (if the command succeeds).
Examples
Add a GIN server repository as a remote named 'primary'
$ gin add-remote primary gin:alice/example
Add a directory on a storage drive as a remote named 'datastore'
$ gin add-remote datastore dir:/mnt/gindatastore
Remove a remote from the current repository
gin remove-remote <name>
Description
Remove a remote from the current repository.
Arguments
<name>The name of the remote
Set the repository's default upload remote
gin use-remote [<name>]
Description
Set the default remote for uploading. The default remote is used when 'gin upload' is invoked without specifying the --to option.
With no arguments, this command simply prints the currently configured default remote.
Arguments
<name>The name of the remote to use by default
List the repository's configured remotes
gin remotes
Description
List configured remotes and their information.
Flags
--json: Print output in JSON format.
Add a new GIN server configuration
gin add-server [--web http[s]://<hostname>[:<port>]] [--git [<gituser>@]<hostname>[:<port>]] <alias>
Description
Configure a new GIN server that can be used to add remotes to repositories.
The command requires only one argument, the alias for the server. All other information can be provided on the command line using the flags described below. You will be prompted for any required information that is not provided.
When configuring a server, you must specify an alias (name) for it, which will be used to refer to the configured server. This alias is then used when adding a remote to a repository. The default G Node GIN server is available under the name 'gin', but this may be overridden. The word 'dir' cannot be used as is has special meaning when adding a remote to a repository. See 'gin help add-remote'.
The following information is required to configure a new server:
For the web server: the protocol, hostname, and port
The protocol should be either 'http' or 'https'.
The hostname for the server (e.g., gin.g-node.org).
The web port for the server (e.g., 80, 443).
For the git server: the git user, hostname, and port
The git user is the username set on the server for managing the repositories. It is almost always 'git'.
The hostname for the git server (e.g., git.g-node.org).
The git port for the server (e.g., 22, 2222).
See the Examples section for a full example.
Arguments
<alias>The alias (name) for the server.
Flags
--git: Set the user, address and port for the git server.--web: Set the address and port for the web server.
Examples
This is what configuring the built-in G-Node GIN server would look like (note: this is already configured)
$ gin add-server --web https://gin.g-node.org:443 --git git@gin.g-node.org:22 gin
Remove a server from the global configuration
gin remove-server <alias>
Description
Remove a server from the global configuration.
Arguments
<alias>The alias (name) of the server in the configuration
Set the default server for the client
gin use-server [<name>]
Description
Set the default GIN server for user and repository management commands.
The following commands are affected by this setting: create, info, keys, login, logout, repoinfo, repos
This setting can be overridden in each command by using the --server flag.
With no arguments, this command simply prints the currently configured default server.
Arguments
<name>The name of the server to use by default
List the globally configured servers
gin servers
Description
List globally configured servers and their information.
Flags
--json: Print output in JSON format.
Roll back files or directories to older versions
gin version [--json] [--max-count n | --id hash | --copy-to location] [<filenames>]...
Description
Roll back directories or files to older versions.
Arguments
<filenames>One or more directories or files to roll back.
Flags
--copy-to: Retrieve files from history and copy them to a new location instead of overwriting the existing ones. The new files will be placed in the directory specified and will be renamed to include the date and time of their version.--id: Commit ID (hash) to return to.--json: Print output in JSON format.--max-count: Maximum number of versions to display before prompting. 0 means 'all'.
Examples
Show the 50 most recent versions of recordings.nix and prompt for version
$ gin version -n 50 recordings.nix
Return the files in the code/ directory to the version with ID 429d51e
$ gin version --id 429d51e code/
Retrieve all files from the code/ directory from version with ID 918a06f and copy it to a directory called oldcode/
$ gin version --id 918a06f --copy-to oldcode code
Show the 15 most recent versions of data.zip, prompt for version, and copy the selected version to the current directory
$ gin version -n 15 --copy-to . data.zip
Print a user's information
gin info [username]
Description
Print user information. If no argument is provided, it will print the information of the currently logged in user. Using this command with no argument can also be used to check if a user is currently logged in.
Arguments
<username>The name of the user whose information should be printed. This can be the username of the currently logged in user (default), in which case the command will print all the profile information with indicators for which data is publicly visible. If it is the username of a different user, only the publicly visible information is printed.
Flags
--json: Print output in JSON format.--server: Specify server alias for info lookup. See also 'gin servers'.
List, add, or delete public keys on the GIN services
gin keys [--add <filename> | --delete <keynum> | --verbose | -v]
Description
List, add, or delete SSH keys. If no argument is provided, a numbered list of key names is printed. The key number can be used with the '--delete' flag to remove a key from the server.
The command can also be used to add a public key to your account from an existing filename (see '--add' flag).
Flags
--add: Specify a filename which contains a public key to be added to the GIN server.--delete: Specify a number to delete the corresponding key from the server. Use 'gin keys' to get the numbered listing of keys.--json: Print output in JSON format.--server: Specify server alias to query, add, or remove keys. See also 'gin servers'.--verbose: Verbose printing. Prints the entire public key.
Examples
Add a public key to your account, as generated from the default ssh-keygen command
$ gin keys --add ~/.ssh/id_rsa.pub
Show the information for a specific repository
gin repoinfo --json <repopath>
Description
Show the information for a specific repository on the server.
This can be used to check if the logged in user has access to a specific repository.
Arguments
<repopath>The repository path must be specified on the command line. A repository path is the owner's username, followed by a "/" and the repository name.
Flags
--json: Print information in JSON format.--server: Specify server alias where the repository will be created. See also 'gin servers'.
Sync all new information bidirectionally between local and remote repositories
gin sync [--json] [--content]
Description
Synchronises changes bidirectionally between remote repositories and the local clone. This will create new files that were added remotely, delete files that were removed, and update files that were changed.
Optionally downloads and uploads the content of all files in the repository. If 'content' is not specified, new files will be empty placeholders. Content of individual files can later be retrieved using the 'get-content' command.
Flags
--content: Download and upload the content for all files in the repository.--json: Print output in JSON format.
List available remote repositories
gin repos [--shared | --all | <username>]
Description
List repositories on the server that provide read access. If no argument is provided, it will list the repositories owned by the logged in user.
Note that only one of the options can be specified.
Arguments
<username>The name of the user whose repositories should be listed. The list consists of public repositories and repositories shared with the logged in user.
Flags
--all: List all repositories accessible to the logged in user.--json: Print output in JSON format.--server: Specify server alias where the repository will be created. See also 'gin servers'.--shared: List all repositories that the user is a member of (excluding own repositories).
Achilleas Koutsou edited this page 4 years ago
Delete Page