// Copyright 2013 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

/*
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.

*/
package main