Hangar CLI Documentation

The CLI described below is automatically available after the Hangar Python package has been installed (either through a package manager or via source builds). In general, the commands require the terminals cwd to be at the same level the repository was initially created in.

Simply start by typing $ hangar --help in your terminal to get started!

hangar

hangar [OPTIONS] COMMAND [ARGS]...

Options

--version

display current Hangar Version

branch

operate on and list branch pointers.

hangar branch [OPTIONS] COMMAND [ARGS]...

create

Create a branch with NAME at STARTPOINT (short-digest or branch)

If no STARTPOINT is provided, the new branch is positioned at the HEAD of the staging area branch, automatically.

hangar branch create [OPTIONS] NAME [STARTPOINT]

Arguments

NAME

Required argument

STARTPOINT

Optional argument

delete

Remove a branch pointer with the provided NAME

The NAME must be a branch present on the local machine.

hangar branch delete [OPTIONS] NAME

Options

-f, --force

flag to force delete branch which has un-merged history.

Arguments

NAME

Required argument

list

list all branch names

Includes both remote branches as well as local branches.

hangar branch list [OPTIONS]

checkout

Checkout writer head branch at BRANCHNAME.

This method requires that no process currently holds the writer lock. In addition, it requires that the contents of the staging area are ‘CLEAN’ (no changes have been staged).

hangar checkout [OPTIONS] BRANCHNAME

Arguments

BRANCHNAME

Required argument

clone

Initialize a repository at the current path and fetch updated records from REMOTE.

Note: This method does not actually download the data to disk. Please look into the fetch-data command.

hangar clone [OPTIONS] REMOTE

Options

--name <name>

first and last name of user

--email <email>

email address of the user

--overwrite

overwrite a repository if it exists at the current path

Arguments

REMOTE

Required argument

column

Operations for working with columns in the writer checkout.

hangar column [OPTIONS] COMMAND [ARGS]...

create

Create an column with NAME and DTYPE of SHAPE.

The column will be created in the staging area / branch last used by a writer-checkout. Valid NAMEs contain only ascii letters and ['.', '_', '-'] (no whitespace). The DTYPE must be one of ['UINT8', 'INT8', 'UINT16', 'INT16', 'UINT32', 'INT32', 'UINT64', 'INT64', 'FLOAT16', 'FLOAT32', 'FLOAT64', 'STR'].

If a ndarray dtype is specified (not ‘STR’), then the SHAPE must be the last argument(s) specified, where each dimension size is identified by a (space seperated) list of numbers.

Examples:

To specify, an column for some training images of dtype uint8 and shape (256, 256, 3) we should say:

$ hangar column create train_images UINT8 256 256 3

To specify that the samples can be variably shaped (have any dimension size up to the maximum SHAPE specified) we would say:

$ hangar column create train_images UINT8 256 256 3 --variable-shape

or equivalently:

$ hangar column create --variable-shape train_images UINT8 256 256 3

To specify that the column contains a nested set of subsample data under a common sample key, the --contains-subsamples flag can be used.

$ hangar column create --contains-subsamples train_images UINT8 256 256 3
hangar column create [OPTIONS] NAME [UINT8|INT8|UINT16|INT16|UINT32|INT32|UINT
                     64|INT64|FLOAT16|FLOAT32|FLOAT64|STR] [SHAPE]...

Options

--variable-shape

flag indicating sample dimensions can be any size up to max shape.

--contains-subsamples

flag indicating if this is a column which nests multiple subsamples under a common sample key.

Arguments

NAME

Required argument

DTYPE

Required argument

SHAPE

Optional argument(s)

remove

Delete the column NAME (and all samples) from staging area.

The column will be removed from the staging area / branch last used by a writer-checkout.

hangar column remove [OPTIONS] NAME

Arguments

NAME

Required argument

commit

Commits outstanding changes.

Commit changes to the given files into the repository. You will need to ‘push’ to push up your changes to other repositories.

hangar commit [OPTIONS]

Options

-m, --message <message>

The commit message. If provided multiple times each argument gets converted into a new line.

diff

Display diff of DEV commit/branch to MASTER commit/branch.

If no MASTER is specified, then the staging area branch HEAD will will be used as the commit digest for MASTER. This operation will return a diff which could be interpreted as if you were merging the changes in DEV into MASTER.

TODO: VERIFY ORDER OF OUTPUT IS CORRECT.

hangar diff [OPTIONS] DEV [MASTER]

Arguments

DEV

Required argument

MASTER

Optional argument

export

Export COLUMN sample data as it existed a STARTPOINT to some format and path.

Specifying which sample to be exported is possible by using the switch --sample (without this, all the samples in the given column will be exported). Since hangar supports both int and str datatype for the sample name, specifying that while mentioning the sample name might be necessary at times. It is possible to do that by separating the name and type by a colon.

Example:

  1. if the sample name is string of numeric 10 - str:10 or 10
  2. if the sample name is sample1 - str:sample1 or sample1
  3. if the sample name is an int, let say 10 - int:10
hangar export [OPTIONS] COLUMN [STARTPOINT]

Options

-o, --out <outdir>

Directory to export data

-s, --sample <sample>

Sample name to export. Default implementation is to interpret all input names as string type. As an column can contain samples with both str and int types, we allow you to specify name type of the sample. To identify a potentially ambiguous name, we allow you to prepend the type of sample name followed by a colon and then the sample name (ex. str:54 or int:54). this can be done for any sample key.

-f, --format <format_>

File format of output file

--plugin <plugin>

override auto-inferred plugin

Arguments

COLUMN

Required argument

STARTPOINT

Optional argument

fetch

Retrieve the commit history from REMOTE for BRANCH.

This method does not fetch the data associated with the commits. See fetch-data to download the tensor data corresponding to a commit.

hangar fetch [OPTIONS] REMOTE BRANCH

Arguments

REMOTE

Required argument

BRANCH

Required argument

fetch-data

Get data from REMOTE referenced by STARTPOINT (short-commit or branch).

The default behavior is to only download a single commit’s data or the HEAD commit of a branch. Please review optional arguments for other behaviors

hangar fetch-data [OPTIONS] REMOTE STARTPOINT

Options

-d, --column <column>

specify any number of column keys to fetch data for.

-n, --nbytes <nbytes>

total amount of data to retrieve in MB/GB.

-a, --all-history

Retrieve data referenced in every parent commit accessible to the STARTPOINT

Arguments

REMOTE

Required argument

STARTPOINT

Required argument

import

Import file or directory of files at PATH to COLUMN in the staging area.

If passing in a directory, all files in the directory will be imported, if passing in a file, just that files specified will be imported

hangar import [OPTIONS] COLUMN PATH

Options

--branch <branch>

branch to import data

--plugin <plugin>

override auto-infered plugin

--overwrite

overwrite data samples with the same name as the imported data file

Arguments

COLUMN

Required argument

PATH

Required argument

init

Initialize an empty repository at the current path

hangar init [OPTIONS]

Options

--name <name>

first and last name of user

--email <email>

email address of the user

--overwrite

overwrite a repository if it exists at the current path

log

Display commit graph starting at STARTPOINT (short-digest or name)

If no argument is passed in, the staging area branch HEAD will be used as the starting point.

hangar log [OPTIONS] [STARTPOINT]

Arguments

STARTPOINT

Optional argument

push

Upload local BRANCH commit history / data to REMOTE server.

hangar push [OPTIONS] REMOTE BRANCH

Arguments

REMOTE

Required argument

BRANCH

Required argument

remote

Operations for working with remote server references

hangar remote [OPTIONS] COMMAND [ARGS]...

add

Add a new remote server NAME with url ADDRESS to the local client.

This name must be unique. In order to update an old remote, please remove it and re-add the remote NAME / ADDRESS combination

hangar remote add [OPTIONS] NAME ADDRESS

Arguments

NAME

Required argument

ADDRESS

Required argument

list

List all remote repository records.

hangar remote list [OPTIONS]

remove

Remove the remote server NAME from the local client.

This will not remove any tracked remote reference branches.

hangar remote remove [OPTIONS] NAME

Arguments

NAME

Required argument

server

Start a hangar server, initializing one if does not exist.

The server is configured to top working in 24 Hours from the time it was initially started. To modify this value, please see the --timeout parameter.

The hangar server directory layout, contents, and access conventions are similar, though significantly different enough to the regular user “client” implementation that it is not possible to fully access all information via regular API methods. These changes occur as a result of the uniformity of operations promised by both the RPC structure and negotiations between the client/server upon connection.

More simply put, we know more, so we can optimize access more; similar, but not identical.

hangar server [OPTIONS]

Options

--overwrite

overwrite the hangar server instance if it exists at the current path.

--ip <ip>

the ip to start the server on. default is localhost [default: localhost]

--port <port>

port to start the server on. default in 50051 [default: 50051]

--timeout <timeout>

time (in seconds) before server is stopped automatically [default: 86400]

status

Display changes made in the staging area compared to it’s base commit

hangar status [OPTIONS]

summary

Display content summary at STARTPOINT (short-digest or branch).

If no argument is passed in, the staging area branch HEAD wil be used as the starting point. In order to recieve a machine readable, and more complete version of this information, please see the Repository.summary() method of the API.

hangar summary [OPTIONS] [STARTPOINT]

Arguments

STARTPOINT

Optional argument

view

Use a plugin to view the data of some SAMPLE in COLUMN at STARTPOINT.

hangar view [OPTIONS] COLUMN SAMPLE [STARTPOINT]

Options

-f, --format <format_>

File format of output file

--plugin <plugin>

Plugin name to use instead of auto-inferred plugin

Arguments

COLUMN

Required argument

SAMPLE

Required argument

STARTPOINT

Optional argument

writer-lock

Determine if the writer lock is held for a repository.

Passing the –force-release flag will instantly release the writer lock, invalidating any process which currently holds it.

hangar writer-lock [OPTIONS]

Options

--force-release

force release writer lock from the CLI.