github.com/motemen/ghq@v1.0.3/README.adoc (about)

     1  = ghq(1) image:https://github.com/motemen/ghq/workflows/test/badge.svg?branch=master["Build Status", link="https://github.com/motemen/ghq/actions?workflow=test"] image:https://coveralls.io/repos/motemen/ghq/badge.svg?branch=master["Coverage", link="https://coveralls.io/r/motemen/ghq?branch=master"]
     2  
     3  == NAME
     4  
     5  ghq - Manage remote repository clones
     6  
     7  == DESCRIPTION
     8  
     9  'ghq' provides a way to organize remote repository clones, like +go get+ does. When you clone a remote repository by +ghq get+, ghq makes a directory under a specific root directory (by default +~/ghq+) using the remote repository URL's host and path.
    10  
    11      $ ghq get https://github.com/motemen/ghq
    12      # Runs `git clone https://github.com/motemen/ghq ~/ghq/github.com/motemen/ghq`
    13  
    14  You can also list local repositories (+ghq list+).
    15  
    16  == SYNOPSIS
    17  
    18  [verse]
    19  ghq get [-u] [-p] [--shallow] [--vcs <vcs>] [--look] [--silent] [--branch] [--no-recursive] <repository URL>|<host>/<user>/<project>|<user>/<project>|<project>
    20  ghq list [-p] [-e] [<query>]
    21  ghq create [--vcs <vcs>] <repository URL>|<host>/<user>/<project>|<user>/<project>|<project>
    22  ghq root [--all]
    23  
    24  == COMMANDS
    25  
    26  get::
    27      Clone a remote repository under ghq root directory (see
    28      <<directory-structures,DIRECTORY STRUCTURES>> below). If the repository is
    29      already cloned to local, nothing will happen unless '-u' ('--update')
    30      flag is supplied, in which case the local repository is updated ('git pull --ff-only' eg.).
    31      When you use '-p' option, the repository is cloned via SSH protocol. +
    32      If there are multiple +ghq.root+ s, existing local clones are searched
    33      first. Then a new repository clone is created under the primary root if
    34      none is found. +
    35      With '--shallow' option, a "shallow clone" will be performed (for Git
    36      repositories only, 'git clone --depth 1 ...' eg.). Be careful that a
    37      shallow-cloned repository cannot be pushed to remote.
    38      Currently Git and Mercurial repositories are supported. +
    39      With '--branch' option, you can clone the repository with specified
    40      repository. This option is currently supported for Git, Mercurial,
    41      Subversion and git-svn. +
    42      The 'ghq' gets the git repository recursively by default. +
    43      We can prevent it with '--no-recursive' option.
    44  
    45  list::
    46      List locally cloned repositories. If a query argument is given, only
    47      repositories whose names contain that query text are listed. '-e'
    48      ('--exact') forces the match to be an exact one (i.e. the query equals to
    49      _project_, _user_/_project_ or _host_/_user_/_project_)
    50      If '-p' ('--full-path') is given, the full paths to the repository root are
    51      printed instead of relative ones.
    52  
    53  root::
    54      Prints repositories' root (i.e. `ghq.root`). Without '--all' option, the
    55      primary one is shown.
    56  
    57  create::
    58      Creates new repository.
    59  
    60  == CONFIGURATION
    61  
    62  Configuration uses 'git-config' variables.
    63  
    64  ghq.root::
    65      The path to directory under which cloned repositories are placed. See
    66      <<directory-structures,DIRECTORY STRUCTURES>> below. Defaults to +~/ghq+. +
    67      This variable can have multiple values. If so, the last one becomes
    68      primary one i.e. new repository clones are always created under it. You may
    69      want to specify "$GOPATH/src" as a secondary root (environment variables
    70      should be expanded.)
    71  
    72  ghq.<url>.vcs::
    73      ghq tries to detect the remote repository's VCS backend for non-"github.com"
    74      repositories.  With this option you can explicitly specify the VCS for the
    75      remote repository. The URL is matched against '<url>' using 'git config --get-urlmatch'. +
    76      Accepted values are "git", "github" (an alias for "git"), "subversion",
    77      "svn" (an alias for "subversion"), "git-svn", "mercurial", "hg" (an alias for "mercurial"),
    78      "darcs", "fossil", "bazaar", and "bzr" (an alias for "bazaar"). +
    79      To get this configuration variable effective, you will need Git 1.8.5 or higher. +
    80      For example in .gitconfig:
    81  
    82  ghq.<url>.root::
    83      The "ghq" tries to detect the remote repository-specific root directory. With this option,
    84      you can specify a repository-specific root directory instead of the common ghq root directory. +
    85      The URL is matched against '<url>' using 'git config --get-urlmatch'.
    86  
    87  ....
    88  [ghq "https://git.example.com/repos/"]
    89  vcs = git
    90  root = ~/myproj
    91  ....
    92  
    93  == ENVIRONMENT VARIABLES
    94  
    95  GHQ_ROOT::
    96      If set to a path, this value is used as the only root directory regardless
    97      of other existing ghq.root settings.
    98  
    99  == [[directory-structures]]DIRECTORY STRUCTURES
   100  
   101  Local repositories are placed under 'ghq.root' with named github.com/_user_/_repo_.
   102  
   103  ....
   104  ~/ghq
   105  |-- code.google.com/
   106  |   `-- p/
   107  |       `-- vim/
   108  `-- github.com/
   109      |-- google/
   110      |   `-- go-github/
   111      |-- motemen/
   112      |   `-- ghq/
   113      `-- urfave/
   114          `-- cli/
   115  ....
   116  
   117  
   118  == [[installing]]INSTALLATION
   119  
   120  === homebrew
   121  
   122  ----
   123  brew install ghq
   124  ----
   125  
   126  === go get
   127  
   128  ----
   129  go get github.com/motemen/ghq
   130  ----
   131  
   132  === build
   133  
   134  ----
   135  git clone https://github.com/motemen/ghq .
   136  make install
   137  ----
   138  
   139  Built binaries are available from GitHub Releases.
   140  https://github.com/motemen/ghq/releases
   141  
   142  == HANDBOOK
   143  
   144  You can buy "ghq-handbook" from Leanpub for more detailed usage.
   145  
   146  https://leanpub.com/ghq-handbook (Currently Japanese Only)
   147  
   148  The source Markdown files of this book are also available for free from the following repository.
   149  
   150  https://github.com/Songmu/ghq-handbook
   151  
   152  == AUTHOR
   153  
   154  * motemen <motemen@gmail.com>
   155  ** https://github.com/sponsors/motemen
   156  * Songmu <y.songmu@gmail.com>
   157  ** https://github.com/sponsors/Songmu