hv command reference manual
hv credentials
In order to connect to the vault server, hv must at least have:
a username
a password
a hostname
For example:
There are 3 ways to specify credentials (in decreasing order of priority):
providing them as command-line arguments (as in the example above)
storing them in environment variables
storing them in the registry+keychain (recommended)
All credentials, including usernames, are case-senstive, meaning that "Joe" and "joe" would be different users.
Command line
Passing credentials on the command line will always take precedence over environment variables and registry+keychain.
-uUSERNAME
specify username
-pPASSWORD
specify password
-hHOST
specify host (server:port) (if port is omitted, defaults to 65433)
-sSITENAME
specify site
--set
remember credentials. This option doesn’t require the credentials to be passed through the command line, credentials passed through environment variables will work as well
Environment variables
Credentials can also be passed through environment variables. They will take precedence over those possibly found in the registry+keychain.
VAULT_HOST
the server host name
VAULT_PORT
the server port
VAULT_USER
the username to connect to the server
VAULT_PASS
the user’s password
VAULT_SITE
the site to use (most commands need a site to operate)
Registry + keychain
Unless environment variables or command-line arguments are provided, hv
will look for credentials in the registry (and the OS’s keychain for passwords.)
Credentials can be stored in the registry (and keychain) like so:
The user, host (and optional site) will be persisted in the registry, while the password will be saved to the OS’s keychain.
For this operation to succeed, at least a user and host must be provided
In order to keep the various commands' syntax as clear as possible, we will assume that the user has stored credentials (in either the registry+keychain or environment variables) for the rest of this manual.
Best practices
We recommend persisting credentials using the registry+keychain method.
Once that is done, commands will become cleaner:
if you login to the server using hvui
and save the login information, it will end up in the the registry+keychain method, and thus hv
will then be able to use that information as well.
Path formats
Local paths refer to a file on the host file system.
Vault paths refer to a file mapped on the vault. They can start with //
to refer to the root of the vault.
Some vault paths can optionally specify the revision of the path.
Special symbols were created to access specific revisions:
^
last revision available on the vault
=
current revision, that is synced on the site
*
all revisions
Special file revision symbols
subdir/
means all files in all subdirectories
subdir
means all files in all subdirectories (same as subdir/)
subdir/*
means all files in the directory
Directories and wildcards
Examples
Get the first revision of a file:
Sync to the last version of a file:
Force sync to the current revision (we must specify -f to force a file transfer):
Display md5 checksums of all revisions of a file:
List Hex-Rays Vault server’s toplevel directory contents:
Plan to add a file to the vault:
Plan to add a directory:
Plan to delete a file:
Show worklist to which files were added:
It is safe to interrupt a command using Ctrl-C. The file transfers in action will be gracefully terminated, so that no partially received files will be left on the disk. However, the requests that were delivered to the server will still be carried out up to the completion. For example, if the user asked to check out thousands of files for editing, this will be performed even if the user presses Ctrl-C after invoking the command.
If the command syntax specifies ellipsis (…), it means that multiple path patterns can be specified. The path patterns can be specified using local paths or vault paths, which start with a double slash (//
).
Commands
Sites
Commands in this section manipulate sites.
A user must be using a site in order for most commands to work correctly.
site add
site add
site add [-u USER] SITENAME ROOTDIR [HOST]
Creates a new site.
The specified user will be the owner of the new site. If the user is not specified, the current user will own the site. Only the site owner can use a site.
Only admins can create sites for other users.
To use a site, it must be specified as described in the credentials section.
-u USER
The user (owner) of the new site, must be an existing username. Defaults to the current user. Admins can specify a different user.
SITENAME
The name of the site that will be created, it must be unique (no site can already exist with that name). It must not exceed 64 characters, and it must be composed of alphanumerics or underscore or dash. The first character cannot be a digit or a dash.
ROOTDIR
The absolute path to the directory that will hold the vault files.
HOST
The computer from which the site can be used. It can be specified as an empty string. In this case the server will let the site to be used by any computer. However, since it is a safety feature that prevents from inadvertently using a site from a wrong computer, we do not recommend to specify it as an empty string. When creating a site for the current user, the host defaults to the current computer.
Parameters
Examples:
Create a new site:
Ensure that is exists:
Remember the new site in the registry:
The new site is used in all future commands: