Setup: GIN Client

Contents

  1. Quickstart
  2. Windows
  3. macOS
  4. Linux
  5. Compiling from source

Quickstart

The GIN command line client is a tool for managing your data repositories, whether they are stored on the public GIN service, a self hosted GIN instance, or your local hard drive. The client is based on git and git-annex and works partially as a wrapper for the two utilities.

The GIN command line client is available for Windows, macOS, and Linux.

Latest version downloads (see the corresponding section for each OS for details):

Bundles vs Client Only packages

On some operating systems, it's less straightforward than others to install the dependencies, in particular git-annex. For these systems, we build bundles which include everything required to run the client. In general, you can determine whether you need a bundle or not with the following steps:

  1. If you have git and git-annex installed, you only need to download and install the GIN client.
  2. If you do not have git or git-annex installed, we recommend you to download and install the GIN client bundle/package. This will take care of everything for you.
  3. If you are not sure, open your terminal and type git --version as well as git annex version. If git annex version doesn't produce an error and the printed version is version 7 or newer, you can download the client only package for your operating system.

Windows

For Windows, we provide two bundled packages, a 32-bit and a 64-bit package. Both include everything required to run the client.

How to decide which package you need:

  • The 32-bit version can only manage files up to 4 GB in size, so if you are handling bigger files you need to install the 64-bit version (assuming you can run it; see the next point).
  • 32-bit versions of Windows can only use the 32-bit package. Windows 64-bit can use both 32 and 64-bit versions. If you would like to use the 64-bit version and are unsure if you are running 64-bit Windows, the Microsoft Windows support site has a quick guide for determining your installed version.
  • The 64-bit package includes the 64-bit version of git-annex. This version does not include all the features of the 32-bit version, but none of the missing features are required to work with GIN. See the git-annex support site for more information.

To install:

  • Download the 32-bit zip file or the 64-bit zip file.
  • Extract it anywhere on your hard drive (e.g., C:\gin).
  • Navigate to the extracted gin directory and double click the set-global.bat file.
    • This will make the gin command available in the Windows console by adding the location of the GIN CLI files to your system PATH.
  • Alternatively, you can use the gin-shell.bat to run a standalone shell. This will present you with a command prompt that is ready to use the client.

Verify the installation:

  • gin --version shows the installed version of the GIN CLI, git, and git-annex.
  • Type gin --help to see the available commands and their description.
  • You can see detailed help for individual commands by typing gin help followed by the command name (e.g., gin help create).

Download links

macOS

The easiest way to install the client on macOS is via homebrew. G-Node homebrew formulae are maintained in the G-Node tap. Install the client, including any dependencies, with:

brew tap g-node/pkg
brew install g-node/pkg/gin-cli

If you don't want to use homebrew, we provide two packages for macOS.

Bundle

The macOS bundle contains an .app file that contains all software and libraries required to use the GIN client. To use it, simply download the archive, double click in the Finder to extract the contents, open the new directory, and drag the contained .app file to your Applications folder. Double clicking the application will launch a Terminal that's ready to use the client.

Note that you may get a warning that the "gin-cli.app" is from an unknown developer. If the "Open" button does not appear on this dialogue box, you can run it by right clicking the .app icon and selecting "Open".

Binary (client only)

Alternatively, if you already have git and git-annex installed on your system, or you want to install them manually or via homebrew, follow the instructions below:

The recommended and simplest way to install git-annex is via Homebrew using brew install git-annex. Alternatively, download git-annex from the git-annex website.

Once you've installed git-annex, simply download the gin client for macOS, extract the archive, and put the file named gin in a location that's included in your $PATH.

Type gin --help to see the available commands and their description.

Download links

Linux

There are two ways how you can install the GIN client: via downloading the Bundle (for Debian-based distributions only) which includes its git and git-annex dependencies or via downloading only the GIN client itself.

Bundle

The Bundle for Debian-based distributions (including Ubuntu and derivatives) can be downloaded here as a deb file. It includes the GIN client as well as git-annex. Simply download the bundle, install it and you should be all set. To install, double click the .deb file or from the command line type dpkg -i gin-cli-latest.deb from the directory in which it was downloaded.

Binary (client only)

Downloading the GIN client without its dependencies is recommended if you already have git-annex set up. You only need to download the client, extract the archive, and put the file named gin in a location that's included in your $PATH. If you struggle, here is a StackOverflow Post dealing with this issue.

If your distribution does not provide git-annex, or provides a version prior to version 7 you can download and install it manually.

For Arch Linux, the GIN client is available in the AUR.

Type gin --help to see the available commands and their description.

Download links

Compiling from source

The GIN client is written in Go. To build the client from source, you need a working Go installation. See the official Go Programming Language Getting Started guide for instructions on installing the compiler and related tools.

The source code for the GIN client can be found on GitHub at https://github.com/G-Node/gin-cli. The binary can be built and copied to the Go bin directory automatically using make install. Alternatively, if make isn't available, it can be built and installed by running go install from the root of the repository. Note that building using go install creates an executable called gin-cli (or gin-cli.exe on Windows).

Important note: When compiling from source, git and git-annex (v7+) need to be installed for all client features to be available.

Achilleas Koutsou edited this page 1 month ago