Translate to English

README.en.md

@@ -0,0 +1,41 @@
+ghq handbook
+============
+
+[日本](README.md) | English
+
+This repository explains how to use [ghq](https://github.com/x-motemen/ghq), a command-line tool that makes it convenient to retrieve and manage source code repositories.
+
+You can purchase this document as an ebook from [Leanpub](https://leanpub.com/ghq-handbook).
+
+Pulls requests are also welcome.
+
+## Table of Contents
+
+### Overview and Usage
+
+1. [Introduction](en/01-introduction.md)
+2. [Basic Usage](en/02-basic-usage.md)
+
+### Commands
+
+3. [Setting the target directory (`ghq root`)](en/03-ghq-root.md)
+4. [Fetching repositories (`ghq get`)](en/04-ghq-get.md)
+5. [Getting a list and paths of local repositories (`ghq list`)](en/05-ghq-list.md)
+6. [Creating a local repository (`ghq create`)](en/06-ghq-create.md)
+
+### Appendix
+
+7. [Recipes for batch fetching (`STDIN | ghq get`)](en/07-bulk-ghq-get.md)
+8. [The future of `ghq`](en/08-roadmap.md)
+
+## Author
+
+Masayuki Matsuki ([@songmu](https://github.com/songmu))
+
+## Contributors
+
+- Jules ([@examosa](https://github.com/examosa)) - English translation
+
+## License
+
+[CC BY-NC 3.0](LICENSE)

README.md

@@ -1,6 +1,8 @@
 ghq handbook
 ============
 
+日本 | [English](README.en.md)
+
 このリポジトリは、ソースコードリポジトリの取得・管理を便利にするコマンドラインツール、`ghq`の使い方の説明をするものです。
 
 <https://github.com/x-motemen/ghq>
@@ -9,8 +11,6 @@ ghq handbook
 
 pull requestも受け付けています。
 
-現状日本語のみの提供ですが、将来的には英語も提供したいと考えています。売上を使って外部に発注するかもしれません。もちろん、有志の翻訳も歓迎です。
-
 ## 目次
 
 ### 第1部 イントロダクション
@@ -34,6 +34,10 @@ pull requestも受け付けています。
 
 Songmu (Masayuki Matsuki)
 
+## 貢献者
+
+- Jules ([@examosa](https://github.com/examosa)) - 英語翻訳
+
 ## ライセンス
 
-CC BY-NC 3.0
+[CC BY-NC 3.0](LICENSE)

en/01-introduction.md

@@ -0,0 +1,69 @@
+# Introduction
+
+This document describes the usage of the command line tool, `ghq`. It is written and maintained by Songmu (Masayuki Matsuki): <https://github.com/Songmu>.
+
+The source code of this document is available as Markdown on GitHub: <https://github.com/Songmu/ghq-handbook>.
+
+It can also be purchased as an e-book on LeanPub: <https://leanpub.com/ghq-handbook>.
+
+## What is `ghq`?
+
+`ghq` makes cloning and managing source code repositories easy using these simple ideas:
+
+- `ghq get <target>` retrieves a repository
+    - Targets can be specified in a flexible way
+    - Various different Version Control Systems (or VCSs) can handled transparently
+- `ghq` enforces a unique directory hierarchy
+    - It follows a style of `{{GHQ_ROOT}}/{{HOST}}/{{PATH}}`, inspired by that of `go get`
+
+Go programmers will recognize this as an application of the library-fetching rule of `go get` based on [`GOPATH`](https://golangr.com/what-is-gopath). Not only does it make it easier to manage multiple projects, it allows you to more easily clone the OSS repositories you come across and prevents you from losing track of repositories cloned to ad-hoc directories.
+
+Through the use of interactive filtering tools like `peco` or `fzf`, you can move to any desired directory at a blazing pace even if you have hundreds of repositories cloned. Furthermore, since `ghq` enables you to more easily clone OSS repositories, it augments code reading. As a matter of fact, the author has more than a thousand repositories cloned locally!
+
+
+The *gh* of `ghq` stands for "GitHub" or "git & hg", whereas the *q* stands for "quick" or 「急」 (hurry, sudden, steep or quick, pronounced "queue"). Something like that...
+
+## Environment
+
+`ghq` is developed on GitHub <https://github.com/motemen/ghq>. It is written in [Go](https://go.dev) and runs on all major platforms. It officially provides 64-bit binary for Linux, MacOS and Windows.
+
+The content of this handbook has been verified using `ghq` v1.0.0, macOS 10.15.2 and zsh 5.7.1. Differences between OSes and shells are accounted for as much as possible.
+
+## Install `ghq`
+
+### Package Manager Overview
+[![Packaging status](https://repology.org/badge/vertical-allrepos/ghq.svg)](https://repology.org/project/ghq/versions)
+
+### Homebrew
+
+```console
+% brew install ghq
+```
+
+### Scoop (Windows)
+
+```console
+% scoop install ghq
+```
+
+### AUR
+
+```console
+% yay -S ghq
+```
+
+### NixOS
+
+```console
+% nix-env -iA nixpkgs.ghq
+```
+
+Alternatively, you can download an executable for your environment from the [GitHub Releases](https://github.com/x-motemen/ghq/releases) page. This can be trivially accomplished with [eget](https://github.com/zyedidia/eget):
+
+```console
+% eget x-motemen/ghq
+```
+
+We recommend using a tagged, stable build version unless you want to contribute to the development of `ghq`.
+
+If you are a contributor or want to build from source, you can `go get` or `git clone` the development repository.

en/02-basic-usage.md

@@ -0,0 +1,58 @@
+# Basic Usage
+
+This chapter explains the basic of using `ghq`. The contents of this chapter encompass a level of proficiency most will already have when they start using `ghq`.
+
+The main functionality of `ghq` revolves around "getting repositories" and "listing retrieved repositories".
+
+## Get a repository - `ghq get`
+
+To learn by example, you can use `ghq get` to retrieve the source repository for `ghq` as follows:
+
+```console
+% ghq get x-motemen/ghq
+```
+
+## List local repostiories - `ghq list`
+
+You can use `ghq list` to get a list of repositories formatted as `{{HOST}}/{{PATH}}`.
+
+```console
+% ghq list
+github.com/x-motemen/ghq
+```
+
+The `--full-path` option can be used to list the repositories by their absolute path.
+
+```console
+% ghq list --full-path
+/Users/Songmu/ghq/github.com/x-motemen/ghq
+```
+
+In the example above, notice that the repository is stored in `/Users/Songmu/ghq`; you can view where `ghq` is cloning repositories with `ghq root`:
+
+```console
+% ghq root
+/Users/Songmu/ghq
+```
+
+As is apparent, `$HOME/ghq` is the default storage directory. This can be changed in the settings.
+
+## Do everything with `ghq get`
+
+The examples above do not do the justice of highlighting the convenience offered by `ghq`. However, once you start using it regularly, you'll wonder how you were ever content with just using `git clone`.
+
+While Git and GitHub are the primary targets for `ghq`, it can retrieve from any repository hosting service and supports the following Source Code Management (SCM) tools:
+
+- [Git](https://git-scm.com/) (`git`)
+- [Mercurial](https://www.mercurial-scm.org/) (`hg`)
+- [Subversion](https://subversion.apache.org/) (`svn`)
+- [git-svn](https://git-scm.com/docs/git-svn) (`git-svn`)
+- [Bazaar](http://bazaar.canonical.com/) (`bzr`)
+- [Fossil](https://fossil-scm.org/) (`fossil`)
+- [Darcs](https://darcs.net/) (`darcs`)
+
+We recommend that you get and manage all of your code using `ghq`, whether it's public, private, for work, a hobby, or anything else.
+
+* * *
+
+In the chapters following, we will go into more detail about each command. Rather than exhaustively describing each of them, we will focus on their primary use cases. When discussing command-line options, the option names will be in long form, but some also provide short options. see the command-line help (`ghq -h`) for more information.

en/03-ghq-root.md

@@ -0,0 +1,47 @@
+# Setting the target repository directory (`ghq root`)
+
+`ghq` clones repositories under `$HOME/ghq` by default. This is configurable.
+
+`ghq` will use the `ghq.root` field in your git config to determine where to clone repositories.
+
+If you are a Go programmer, repositories are typically located under `$GOPATH/src` with the layout expected by `ghq`, so let's set it as follows:
+
+```console
+% git config --global ghq.root '~/go/src'
+```
+
+After running the above command, your `~/.gitconfig` should look like this:
+
+```gitconfig
+[ghq]
+root = ~/go/src
+```
+
+With this in place, `ghq get` will clone repositories to `~/go/src`, and `ghq list` will list them as expected.
+
+However, mixing Go code with code from other languages ​​can be problematic. For such cases, `ghq.root` can be set multiple times.
+
+```gitconfig
+[ghq]
+root = ~/go/src
+root = ~/myprojects
+```
+
+If `ghq.root` is set multiple times, the last value will be used the primary directory. With the above settings, `ghq get` will clone repositories to `~/myprojects`, and `ghq list` will list repositories under both `~/myprojects` and `~/go/src`.
+
+You can check which directory is being used with `ghq root` command:
+
+```console
+% ghq root
+/Users/Songmu/myprojects
+```
+
+`ghq root` will only output the directory with the highest priority, but if multiple are set, `ghq root --all` will output all directories.
+
+```console
+% ghq root --all
+/Users/Songmu/myprojects
+/Users/Songmu/go/src
+```
+
+The `ghq.<base>.root` setting is also listed with `ghq root --all`. `ghq.<base>.root` will be covered in the next chapter, `ghq get`.