English translation of ghq book

README-en.md

@@ -0,0 +1,41 @@
+# ghq handbook
+
+`ghq` is a command line tool which makes it easy to retrieve and manage source code repositories. This repository contains the source code for the book available from leanpub.
+
+<https://github.com/x-motemen/ghq>
+
+You can purchase an e-book version of this document at <https://leanpub.com/ghq-handbook>.
+
+It can also be purchased at <https://zenn.dev/songmu/books/ghq-handbook>.
+
+pull requests are welcome and accepted.
+
+The original book is available in Japanese. This is a volunteer translation into English.
+
+## Table of Contents
+
+### Part 1: Introduction
+
+1. [Introduction](en/01-introduction.md)
+2. [Basic usage](en/02-basic-usage.md)
+
+### Part 2: How to use
+
+3. [Setting the repository acquisition directory (`ghq root`)](en/03-command-root.md)
+4. [Fetching the repository (`ghq get`)](en/04-command-get.md)
+5. [Get the list and path of local repositories (`ghq list`)](en/05-command-list.md)
+6. [Create a local repository (`ghq create`)](en/06-command-create.md)
+
+### Appendix
+
+7. [Recipe collection for bulk repository acquisition (`STDIN | ghq get`)](en/07-bulk-ghq-get.md)
+8. [The future of ghq](en/08-ghq-roadmap.md)
+
+## Author
+
+Code and Japanese Book: Songmu (Masayuki Matsuki)
+English Translation: paul-jewell (Paul Jewell)
+
+## License
+
+CC BY-NC 3.0

en/01-introduction.md

@@ -0,0 +1,45 @@
+---
+title: Introduction
+type: tech
+published: true
+---
+
+# Introduction
+
+This document describes how to use command line tool `ghq`. This document is written by Songmu (Masayuki Matsuki), the maintainer of `ghq`. The English translation is by paul-jewell (Paul Jewell).
+
+The source code for this document is available in Markdown format from the repository https://github.com/Songmu/ghq-handbook.
+
+You can also purchase an e-book version of this document at https://leanpub.com/ghq-handbook.
+
+## What is `ghq`
+
+`ghq`simplifies the acquisition and management of source code repositories. This is due to the following simple idea:
+
+- `ghq get <target>` Easily get the source code for anything
+  - Flexible targeting method
+  - Transparently handle multiple Version Control Systems (VCS)
+- Enforcing a unique directory structure
+  - `go get` layout is based on {{GHQ_ROOT}}/{{HOST}}/{{PATH}}
+
+It will be easy for Go programmers to understand that this `go get` is an application of the library acquisition rules from the GOPATH to things other than Go. By using `ghq`, you will not only be able to manage multiple projects easily, but you will also be able to easily clone the OSS you are interested in, and you will not have to clone the repository to an ad hoc directory and lose track of it.
+
+When `ghq` is combined with interactive filter tools such as `peco` and `fzf`, you can instantly navigate to the desired repository, even if you have hundreds of repositories at hand. Furthermore, since you can casually clone OSS at hand, there is a nice side effect that reading the source code becomes easier. In fact, the author has over 1000 repositories.
+
+In `ghq`, \"gh\" means GitHub (git or hg), and \"q\" means quick or "sudden".
+
+## Operating environment
+
+ghqis developed in the repository https://github.com/x-motemen/ghq on GitHub. It is written in Go and has been tested on multiple OSs. Officially provides 64-bit binary builds for Linux, macOS, and Windows.
+
+When writing this document, we mainly checked using ghq v1.0.0, macOS 10.15.2, and zsh 5.7.1, but we have taken care to minimize differences depending on the OS and shell environment.
+
+## `ghq` Installation
+
+It can be installed with Homebrew.
+
+% brew install ghq
+
+For other environments, you can obtain the executable from GitHub Releases.
+
+If you have a Go development environment, you can use `go get` to fetch the development repository (https://github.com/x-motemen/ghq) or `git clone` and build it yourself, but unless you are a developer of `ghq`, we recommend using a stable build.

en/02-basic-usage.md

@@ -0,0 +1,61 @@
+---
+title: Basic usage
+type: tech
+published: true
+---
+
+# Basic usage
+
+This chapter explains the basic usage of `ghq`. The content of this chapter alone will get you to a level where you won't have any trouble using it on a daily basis.
+
+The `ghq` main functions are only `obtaining repositories` and `listing the obtained repositories`.
+
+## Get the repository `ghq get`
+
+You can use `ghq get` to get the source code of `ghq` using:
+
+```console
+% ghq get x-motemen/ghq
+```
+
+## List local repositories `ghq list`
+
+You can get a list of your repositories in {{HOST}}/{{PATH}} format with `ghq list`.
+
+```console
+% ghq list
+github.com/x-motemen/ghq
+```
+
+You can get a list of full paths by adding the `--full-path` option.
+
+```console
+% ghq list --full-path
+/Users/Songmu/ghq/github.com/x-motemen/ghq
+```
+
+In the above example, the source code is placed below `/Users/Songmu/ghq`. This location can be displayed using the command `ghq root`.
+
+```console
+% ghq root
+/Users/Songmu/ghq
+```
+
+This location is set to `$HOME/ghq` by default. Of course, this can be changed in the settings.
+
+## `ghq get` everything
+
+From the explanation so far, the convenience of `ghq` may not be clear to you. But once you realize how useful it is, you won't be doing `git clone` anymore, and will be using `ghq get` to get your repositories.
+
+The target of `ghq` is not limited to Git and GitHub. Although it is made more convenient for Git and GitHub, it can retrieve source code from any repository host other than GitHub, and supports the following VCSs:
+
+- Git (git)
+- Mercurial (hg)
+- Subversion (svn)
+- git-svn (git-svn)
+- Bazaar (bzr)
+- Fossil
+- Darcs (darcs)
+  We recommend that you use ghq to acquire and manage all public and private, work and hobby codes, Git and other code.
+
+A detailed explanation of `ghq` is provided in the following chapters. Rather than exhaustively explaining each command, each major use case will be explained. When discussing command line options, the option names are always long options, but some options have short options. See the command line help (`ghq -h`) for more details.

en/03-command-root.md

@@ -0,0 +1,51 @@
+---
+title: Setting the repository acquisition directory (ghq root)
+type: tech
+published: true
+---
+
+# Setting the repository acquisition directory (`ghq root`)
+
+`ghq` places the repository under `$HOME/ghq` by default. This can be changed.
+
+`ghq` uses `gitconfig` for configuration. `ghq.root` is the key for the repository acquisition directory. If you are a Go programmer, the repository is located under `$GOPATH/src`, and can be set up as follows:
+
+```console
+% git config --global ghq.root ' ~/go/src '
+```
+
+At this point, the following settings should have been added to `.gitconfig`:
+
+```gitconfig
+[ ghq ]
+root  =  ~/go/src
+```
+
+This way`ghq get` will retrieve the repository in`~/go/src` and you can list it with `ghq list`.
+
+However, there may be cases where it is difficult to mix Go code and code from other languages. For such cases, multiple `ghq.root` settings can be made.
+
+```gitconfig
+[ ghq ]
+root  =  ~/go/src
+root  =  ~/myprojects
+```
+
+If multiple directories are set, the last directory written will be the primary one, and `go get` will retrieve the repository in that directory. With this setting,`ghq get` will retrieve the repository under `~/myprojects`, and `ghq list` will list the repositories under both `~/myprojects` and `~/go/src`.
+
+You can check this setting with the `ghq root` command:
+
+```console
+% ghq root
+/Users/Songmu/myprojects
+```
+
+`ghq root` will output only the one with the highest priority, but if multiple items are set `ghq root --all` will output all.
+
+```console
+% ghq root --all
+/Users/Songmu/myprojects
+/Users/Songmu/go/src
+```
+
+The `ghq.<base>.root` settings for are also listed by `ghq root --all`. `ghq.<base>.root` will be covered in the next chapter.

en/04-command-get.md

@@ -0,0 +1,156 @@
+---
+title: Get the repository (ghq get)
+type: tech
+published: true
+---
+
+# Get the repository (`ghq get`)
+
+`ghq get` takes a target as an argument or via standard input and retrieves its repository.
+
+```console
+% ghq get < target > [ < target > ...]
+% cat repolist.txt | ghq get --parallel
+```
+
+`ghq` interprets this target in a nice way, so you can specify it flexibly.
+
+The basic form of the target is `https://{{Host}}/{{Path}}`. `https://` is always optional, and if the host is `github.com`, it can also be omitted. In other words, the following three have the same meaning.
+
+```console
+% ghq get https://github.com/x-motemen/ghq
+% ghq get github.com/x-motemen/ghq
+% ghq get x-motemen/ghq
+```
+
+Of course, hosts other than GitHub can also be specified.
+
+```console
+% ghq get launchpad.net/terminator
+```
+
+It is also possible to specify a target using a regular repository URL. URLs other than http schemes are also accepted.
+
+```console
+% ghq get [email protected]:x-motemen/ghq.git
+% ghq get svn+ssh://svn.example.com/yourproject
+```
+
+If you use the `ghq get --update` ( -u) option, it will update to the latest state even if the repository has already been acquired.
+
+## If you want to use SSH or obtain a private repository
+
+`ghq` attempts to retrieve the repository using https by default. However, there may be cases where you want to obtain a private repository using SSH, or you may want to push code using SSH even if it is OSS. The detailed settings of Git won't be covered here, but you have the following options to solve this problem.
+
+- Force **SSH** use by configuring `url.<base>.insteadOf`
+- `ghq get` - Use SSH URL as target
+- `ghq get -p` - Switch to SSH acquisition using option
+- Do not use **SSH** (set **git credentials** etc. appropriately and perform **pull** and **push** using **https**)
+
+You can choose your preferred method, but rather than using the -p option to fetch with SSH, it is better to configure Git settings and fetch with **HTTPS**, as it gives a sense of uniformity. The author uses **https** to obtain the source code, and `url.<base>.pushInsteadOf` settings to push via **SSH**.
+
+## Switch the acquisition directory for each project (`ghq.<base>.root`)
+
+`ghq root` settings were mentioned earlier, but you may want to switch the fetch directory and git settings between work and hobby code. This can be achieved with the `ghq.<base>.root` settings.
+
+The following is an example of a configuration that defaults to `~/hobby`, but repositories under your company's GitHub organization or your company's VCS host are placed in `~/work`.
+
+```gitconfig
+[ ghq ]
+root  =  ~/hobby
+
+[ ghq  "https://github.com/mycompany" ]
+root  =  ~/work
+
+[ ghq  "https://myvcs.example.com" ]
+root  =  ~/work
+```
+
+Speaking of Git settings, if you use the `includeIf` setting, you can apply a specific **gitconfig** only to repositories under a specific directory. The following is an example of applying work **gitconfig** (`~/work/.gitconfig`) to the repository under `~/work`.
+
+```gitconfig
+[ includeIf "gitdir: ~/work/"]
+path  =  ~/work/.gitconfig
+```
+
+As a side note, if the `$GHQ**ROOT` environment variable is set, the repository will be acquired under that directory regardless of other `ghq.root` settings. This may also be useful if you want to fetch directories more dynamically.
+
+## `ghq get {{Project}}` owner detection
+
+GitHub's repository path takes the form {{Owner}}/{{Project}}, but if you give `ghq get` the repository name without slashes, like `ghq get {{Project}}`, it will attempt to complete the owner. For example, in my case **(Songmu)**, `ghq get horenso` retrieves the repository `github.com/Songmu/horenso`.
+
+This completion is done in the following order:
+
+- If `ghq.user` is set, use it
+- Infer GitHub username from local environment
+- Login name ( $USERenvironment variable.Environment variable for Windows $USERNAME)
+
+A function is used to estimate 2, `github.com/Songmu/gitconfig.GitHubUser``, so please refer to it if you want to know more.
+
+By the way, you may want to use the repository name instead of using yourself as the completed owner name. For example, **ruby** to **github.com/ruby/ruby**, **vim** to **github.com/vim/vim**, **peco** to **github.com/peco/peco**, etc.
+
+If you prefer this behavior, you can toggle it by setting the setting `ghq.completeUser` to false.
+
+```console
+% git config --global ghq.completeUser false
+```
+
+## Specify VCS ( --vcs)
+
+`ghq get` will try to determine the most appropriate VCS for the specified target, but you optionally use `--vcs` to specify it explicitly. Here is an example from fossil:
+
+```console
+% ghq get --vcs fossil https://www.sqlite.org/src
+```
+
+Also, if you can specify the VCS for a particular repository host by configuring it with `ghq.<base>.vcs`. Here are the settings to retrieve the repository `https://svn.example.com` with Subversion:
+
+```gitconfig
+[ ghq "https://svn.example.com"]
+vcs  =  svn
+```
+
+## Check the source at the same time as acquisition (`--look, -l`)
+
+It's natural to want to see the contents of a repository as soon as you retrieve it. There is a `ghq get --look` option for that. This is a feature inspired by `cpanm --look`, but moves to the fetch directory after repository fetch.
+
+Even if the repository has already been acquired, you will be moved to the directory, so it is useful for temporarily checking the repository at hand. Also, if you run `ghq get --look --update <target>`, you can check the source while updating to the latest version.
+
+Once you have finished checking, exit using the `exit` command.
+
+Also, please use `--look` only for a temporary review of the source, and do not use it to move the working directory.
+
+The `--look` option launches another shell process as a child process, making it appear as though the directory has been moved. This results in unintuitive behavior such as shell settings not being carried over properly and the need to exit when returning. There is also the problem that it takes time to start the shell because it restarts the shell.
+
+Therefore, we recommend that you simply use a CD to move the working directory as shown below.
+
+```console
+% cd $( ghq list --full-path --exact x-motemen/ghq )
+```
+
+This will be explained in the next `ghq --list` chapter, but the standard way to move directories is to work with filter tools like peco and fzf, so we recommend configuring those settings.
+
+## Target relative path specification
+
+A relatively unknown method of specifying a target for `ghq get` is relative path specification.
+
+```console
+% ghq get ../projB
+```
+
+This can be used, for example, if you are working on `github.com/<your-org>/projA` and want to retrieve another repository under the same organization (`projB` in this example).
+
+## More options for `ghq get`
+
+`ghq get` has several options not covered so far:
+
+- --parallel, -P
+  - If there are multiple targets, they will be acquired in parallel. If this option is specified, even if some repositories fail to be retrieved, the error will only be displayed and the command will not be interrupted. We will discuss how to take advantage of this option separately in a later chapter.
+- --shallow
+  - Retrieve repositories quickly by retrieving only the latest history. Only Git, git-svn, Darcs are supported
+- --branch, -b
+  - Get a specified branch. Only Git, git-svn, Mercurial, and Subversion are supported. Especially in the case of Git git clone --single-branch, you can expect high-speed acquisition because you use options.
+- --no-recursive
+  - In the case of Git, submodule acquisition is automatically recursive by default, but this is an option to suppress that.
+- --silent, -s
+  - Reduce `ghq` console output. Specifically, it suppresses the display of external command output. Default is false, but if the `--parallel` option is specified it will be forced to true to avoid mixing outputs.