rx

Overview ¶

The rx command is a dependency and version management system for Go projects. It is built on top of the go tool and utilizes the $GOPATH convention.

Warning ¶

This tool is very much in flux. Don't depend on commands, options, or pretty much anything else being stable yet.

Installation ¶

As usual, the rx tool can be installed or upgraded via the "go" tool:

go get -u kylelemons.net/go/rx

General Usage ¶

The rx command is composed of numerous sub-commands. Sub-commands can be abbreviated to any unique prefix on the command-line. The general usage is:

rx [<options>] [<subcommand> [<suboptions>] [<arguments> ...]]

Options:

--autosave = true           Automatically save dependency graph (disable for concurrent runs)
--max-age  = 1h0m0s         Nominal amount of time before a rescan is done
--rescan   = false          Force a rescan of repositories
--rxdir    = "$HOME/.rx"    Directory in which to save state
-v         = false          Turn on verbose logging

Commands:

help       Help on the rx command and subcommands.
list       List recognized repositories.
tags       List known repository tags.
prescribe  Update the repository to the given tag/rev.
cabinet    Save, list, or restore dependency snapshots.
checkpoint Save, list, or restore global repository version snapshots.

Use "rx help <command>" for more help with a command.

See below for a description of the various sub-commands understood by rx.

Help Command ¶

Help on the rx command and subcommands.

Usage:

rx help [<command>]

Options:

--godoc = false    Dump the godoc output for the command(s)

List Command ¶

List recognized repositories.

Usage:

rx list [<filter>]

Options:

-f     = ""       List output format
--long = false    Use long output format

The list command scans all available packages and collects information about their repositories. By default, each repository is listed along with its dependencies and contained packages. If a <filter> regular expression is provided, only repositories whose root path matches the filter will be listed.

The -f option takes a template as a format. The data passed into the template invocation is an (rx/graph) Graph, and the default format is:

{{range .Repository}}{{.}} :{{range .Packages}}{{$pkg := index $.Package .}} {{$pkg.Name}}{{end}}
{{end}}

If you specify --long, the format will be:

{{range .Repository}}Repository ({{.VCS}}) {{.}}:
    Packages:{{range .Packages}}
        {{$pkg := index $.Package .}}{{$pkg.ImportPath}}{{end}}
{{with $.RepoDeps .}}    Dependencies:{{range .}}
        {{.}}{{end}}
{{end}}{{with $.RepoUsers .}}    Users:{{range .}}
        {{.}}{{end}}
{{end}}
{{end}}

Tags Command ¶

List known repository tags.

Usage:

rx tags <repo>

Options:

--down = false    Only show downgrades
-f     = ""       tags output format
--long = false    Use long output format
--up   = false    Only show updates (overrides --down)

The tags command scans the specified repository and lists information about its tags. The <repo> can be a full repository path, the last element of a repository path, or any substring of the path as long as it is unique.

The -f option takes a template as a format. The data passed into the template invocation is an (rx/graph) TagList, and the default format is:

{{range .}}{{.Rev}} {{.Name}}
{{end}}

Prescribe Command ¶

Update the repository to the given tag/rev.

Usage:

rx prescribe <repo> <tag>

Options:

--build    = true     build all updated packages
--cascade  = true     recursively process depending packages too
--install  = true     install all updated packages
--link     = false    link and install all updated binaries
--rollback = true     automatically roll back failed upgrade
--test     = true     test all updated packages

The prescribe command updates the repository to the named tag or revision. The <repo> can be a full repository path, the last element of a repository path, or any substring as long as it is unique. The <tag> is anything understood by the underlying version control system as a commit, usually a tag, branch, or commit.

After updating, prescribe will test, build, and the install each package in the updated repository. These steps can be disabled via flags such as "rx prescribe --test=false repo tag".

By default, this will not link and install affected binaries; to turn this behavior on, see the --link option.

Cabinet Command ¶

Save, list, or restore dependency snapshots.

Usage:

rx cabinet <repo> [<id>]

Options:

--build = false    create a new cabinet
--dump  = false    list the contents of the specified cabinet
--list  = true     list matching cabinet files (the default)
--open  = false    open the specified cabinet
--test  = true     test package before saving and after loading cabinet

The cabinet command saves dependency information for the given repository in a file within it. The <repo> can be any piece of the repository root path, as long as it is unique. The <tag> is anything understood by the underlying version control system as a commit, usually a tag, branch, or commit. When saving, the <id> will override the default (based on the date) and when opening the <id> is the ID (or a unique substring) of the cabinet to open.

Cabinets are currently stored in the repository itself named as follows:

.rx/cabinet-YYYYMMDD-HHMMSS

If the <id> is specified for --build, it will override the date-based portion of the cabinet name. If a cabinet already exists with the name (even if it is a date-based name) it will not be overwritten.

Unless --test=false is specified, the packages in the repository will be tested before a cabinet is created and after a cabinet is restored. If the test before creation fails, the cabinet will not be created. If the test after restoration fails, the repositories will be reverted to their original revisions.

The cabinet format is still in flux.

Checkpoint Command ¶

Save, list, or restore global repository version snapshots.

Usage:

rx checkpoint

Options:

--apply   = 0        apply the specified checkpoint
--delete  = 0        delete the specified checkpoint
--exclude = "^$"     regular expression to exclude saved/restored repositories
--filter  = ".*"     regular expression to filter saved/restored repositories
--list    = false    list checkpoints
-n        = 15       number of checkpoints to list (0 for all)
--save    = ""       save a new checkpoint with the given comment

The checkpoint command is similar to the cabinet command, except that it has global scope and does not run tests when saving or applying.

Checkpoints are intended as lightweight ways to save state and to share state among multiple developers sharing an $RX_DIR. Checkpoints are created with a comment and a global, sequential ID which can be used to retrieve or delete it.

Be careful when using checkpoint --apply, because this will update every repository that rx knows about! They will generally wind up in a detached HEAD state, which may not be what you want. See the --filter and --exclude options, which apply to both --save and --apply, to control what repositories are affected by the operations.