Tutorial

Prerequisites

Using the gin command line client requires an active gin account. You can register by visiting the GIN website.

NB: This tutorial is a work in progress and not all commands are currently covered. More coming soon.

Basic usage

Basic usage help is included in the command line and can be printed using:

gin --help

Extended descriptions of commands can be printed using:

gin help <command>

where <command> can be any one of login, logout, create, get, ls, unlock, lock, upload, download, get-content, remote-content, repos, infos, or keys.

The help text for each command can also be found on the help page of this wiki.

---

Quickstart tutorial

This is a quickstart tutorial. It explains a common workflow that one might go through when using the client. For more detailed descriptions of what each command is doing, read the next section.

Assuming you have registered with the GIN services, you can login from the command line using:

gin login

The command will prompt you for a username and password. If entered correctly, you will be greeted with a confirmation message.

Create a repository

Before uploading any files, you must first create a repository on the server. You can do this using the gin create command.

gin create tutorial

In this example, tutorial is the name of the repository. Repository names must be unique for a user (i.e., a single user cannot have two repositories with the same name) and the full name of a repository is the name of the user who created it, along with the repository name, separated by a /. For example, if user user has a repository called tutorial, the full repository name is user/tutorial.

List repositories on the server

You can see a list of the repositories that you own using:

gin repos user

Omitting the username for this command lists all public repositories. Additionally, you can use the same command to see a list of repositories owned by any given user that are accessible by you.

For instance

gin repos alice

will list all repositories owned by the user alice that you can download. This includes public repositories owned by Alice as well as repositories that Alice has chosen to share with you.

Get gin repository from the server

Once the repository is created on the server, it's time to download the (empty) new repository and initialise the local directory that we will use to upload and download data. As mentioned above, for the tutorial we are assuming the username is user and the repository name is tutorial. The gin get command requires us to specify the full name of the repository.

gin get user/tutorial

This will create a directory called tutorial under the directory that you are working in. Note that the command will fail with an error if a directory called tutorial already exists.

Following this, all upload and download commands should be entered from within the repository's directory.

cd tutorial

Add files to the local directory

Copy some data files, or source code into the tutorial directory using any regular method for copying files.

Upload new files to the server

To upload the files that are now inside the tutorial directory, simply issue the upload command.

gin upload .

This will commit your changes, in other words, it will detect the new files in the directory, add them to the repository, and start uploading to the GIN server.

Every time you perform a gin upload . the changes are saved and uploaded and a checkpoint is made of your data.

The . that follows the upload command specifies that you want to upload every file in the current directory and below. You can instead upload individual files or directories by listing them on the command line.

gin upload file1.data recordings/recording1.h5

This will upload changes made to two files: file1.data and recording1.h5, where the latter is in the recordings directory.

Note that upload here doesn't only mean sending new files and changes to the server. This command sends all changes made in the directory to the server, including deletions, renames, etc. Therefore, if you delete files from the directory on your computer and perform a gin upload, the deletion will also be sent and the file will be removed from the server as well. Such changes can be synchronised without uploading any new files by not specifying any files or directories.

gin upload

Fetch any repository updates from the server

If changes are made to your data elsewhere, for example on another computer, or from another user that you share your data with, you can download these changes by typing the download command from within the repository.

gin download

This command will only download changes made to the repository (file deletions, renames, etc) but any new files are downloaded as placeholders. Placeholder files are empty files that represent files uploaded to the repository but do not hold any of the data. This is useful for downloading the contents of some files without downloading the entire repository.

If you would like to download all the data contained in a repository, you can do so using the --content flag.

gin download --content

This will synchronise the local directory with all changes made on the server and download the content of all files.

Checking the status of your files

While working with GIN repositories you will often need to check the status of your local files with respect to the remote repository. Files can be in one of a number of states:

• Synced
• No local content
• Locally modified (unsaved)
• Locally modified (not uploaded)
• Untracked

To determine the status of files you can use the ls command.

gin ls

This will display all files under the current directory separated by their status. You can also see a full listing of files prefixed by an abbreviated status code.

gin ls --short

As with many other commands, the status of individual files can be determined by specifying the files on the command line.

gin ls file1.data recordings/recording1.h5