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, a 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:
if the sample name is string of numeric 10 -
str:10
or10
if the sample name is
sample1
-str:sample1
orsample1
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 a column can contain samples with both
str
andint
types, we allow you to specifyname 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
orint: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 its 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.