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