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 11 months ago