Local GIN client - Useful recipes and short workflows

Contents

1. Introduction
2. Basic Recipes
3. Versioning Recipes

Introduction

The purpose of this page is to provide quick and easy ways to perform common tasks using the GIN client (referred to here as recipes). It is assumed that you have a working version of the GIN client installed. See the GIN client setup guide if this is not the case. A basic knowledge of how GIN and the client works is also useful, since most of these commands assume you are in a situation where you have a repository with some files that you are working on.

Before using any of these commands, it is recommended that you read the Basic Workflow section in the GIN client Usage Guide.

Note that the commands and explanations on this page are not full tutorials for how the GIN client can be used. This page is not a replacement for the tutorials found on the GIN client Usage Guide They are meant as a quick reference for how to achieve common tasks. We refrain from going into too much detail on this page to allow you to quickly find the recipe you are looking for and use the commands without going into a full description of how each command works in all circumstances.

Common structure

Recipes generally follow the following format, though the numbering and sections aren't used explicitly:

1. Context describes the state you may be in before executing the commands.
   Example: In a cloned repository with files you have changed or added.
2. Goal describes what you want to achieve and what the recipe will accomplish.
   Example: To upload to the GIN server all the changes you made in the local directory.
3. Command(s) is a command or list of commands that when executed will achieve the Goal.
   Example: gin upload <files>

Basic Recipes

Status of files

At any time, from a directory inside a repository, you can see the status of files using:

gin ls

Uploading all files

In a cloned repository with files that have been modified, added, or deleted. The working directory is the root of the repository. To upload all the changes that you made to the GIN server, from the top level directory of the repository run:

gin upload .

Uploading specific files

In a cloned repository with files that have been modified, added, or deleted. To upload the modifications made to some of the existing files and one of the new files, but not the changes made to all files, you can specify which files to upload by listing their names on the command line:

gin upload new_data.csv updated_figure.png paper_draft.pdf

Note: In this example, new_data.csv is a new file, updated_figure.png and paper_draft.pdf are files that are in the repository already and have been modified. Any added, removed, or modified files that are not listed on the command line are not uploaded nor are the changes recorded in the local repository.

Uploading modified files (do not add new)

In a cloned repository with files that have been modified, added, or deleted. To upload the modifications made to all existing files without uploading new files or file deletions, modified files must first be committed so the modifications are picked up by the upload command:

gin ls

Look for modified files

gin commit <names of modified files>
gin upload

Record changes to local repository (no upload)

In a cloned or local-only repository with files that have been modified, added or deleted. To record all changes locally without uploading:

gin commit .

Upload previously recorded changes

In a cloned repository where multiple changes have been recorded but not yet uploaded. To upload all versions of files that have been recorded using commit, simply upload with no arguments:

gin upload

Download all the latest data

In a cloned repository with changes made to the server, either by yourself or by a collaborator. To download all changes and the content of annexed data:

gin download --content

—or—

gin download
gin get-content .

Versioning Recipes

Return to previous version of a file

In a repository with files that have multiple recorded versions. To replace a file called analysis_b.data with the previous version:

gin version analysis_b.data
> Type 2 at the prompt and hit [enter]

—or—

gin version --id "HEAD~1" analysis_b.data

Note: The latest recorded version of the file will be removed from the local directory, but will still be available using the version command again (it will become the new previous version). The first option shows a list of versions and asks which one you want to retrieve. Pressing 2 will be the previous version. 1 is the latest. If you use the second option (with --id "HEAD~1") it will skip the prompt and immediately retrieve the previous version of the file.

Retrieve old version of a single file

In a repository with files that have multiple recorded versions. To retrieve a file called analysis_b.data and place it in a new directory without affecting the current version:

gin version --copy-to "OldData" analysis_b.data
> Type 2 at the prompt and hit [enter]

—or—

gin version --id "HEAD~1" --copy-to "OldData" analysis_b.data

Note: The first option shows a list of versions and asks which one you want to retrieve. Pressing 2 will be the previous version. 1 is the latest. If you use the second option (with --id "HEAD~1") it will skip the prompt and immediately retrieve the previous version of the file.