ghq

https://github.com/x-motemen/ghq
Admin
ghq is a command-line tool for managing and organizing remote repository clones under a structured...
Tokens:36,592
Snippets:519
Trust Score:6
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install ghq with go get

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Install ghq using the go get command.

```bash
go install github.com/x-motemen/ghq@latest

```

--------------------------------

### Build and Install ghq

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Use 'make install' to build and install the ghq project. This command compiles the source code and places the executable in the appropriate location for system-wide use.

```bash
make install       # Build and install
```

--------------------------------

### ghq URL Parsing Examples

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Demonstrates various URL formats supported by `ghq get` for cloning repositories. These examples cover full URLs, host authorities, user/project paths, project names, SCP-like syntax, relative paths, and CodeCommit URIs.

```bash
ghq get https://github.com/x-motemen/ghq              # Full URL
```

```bash
ghq get github.com/x-motemen/ghq                      # Authority
```

```bash
ghq get x-motemen/ghq                                 # User/project
```

```bash
ghq get ghq                                           # Project (with user completion)
```

```bash
ghq get git@github.com:x-motemen/ghq                  # SCP-like
```

```bash
ghq get ./repo                                        # Relative path
```

```bash
ghq get codecommit::us-west-2://account/repo          # CodeCommit
```

--------------------------------

### Install ghq with mise

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Install ghq using the mise tool.

```bash
mise install ghq
mise use ghq

```

--------------------------------

### ghq Get Command Example

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-commands.md

Demonstrates how to clone a repository using the ghq get command. Use options like -u for update, -p for SSH protocol, and --branch to specify a branch. The --parallel flag can be used to import multiple repositories from a file.

```bash
ghq get https://github.com/x-motemen/ghq
```

```bash
ghq get -u -p --branch main https://github.com/x-motemen/ghq
```

```bash
ghq get --parallel < repositories.txt
```

--------------------------------

### URL-Matched Configuration Example

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/configuration.md

Example of setting both VCS and root directory for a specific URL match in .gitconfig.

```ini
[ghq "https://git.example.com/repos/"]
    vcs = git
    root = ~/myproj
```

--------------------------------

### Install ghq with asdf-vm

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Install ghq using the asdf version manager.

```bash
asdf plugin add ghq
asdf install ghq latest

```

--------------------------------

### Install ghq with xbps (Void Linux)

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Install ghq using the xbps package manager on Void Linux.

```bash
xbps-install -S ghq

```

--------------------------------

### Minimal ghq Setup

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/configuration.md

No configuration is needed for a minimal setup; ghq uses the default root directory (~/.ghq) out of the box.

```bash
# Just use default root (~/.ghq)
# No configuration needed, ghq works out of the box
ghq get https://github.com/x-motemen/ghq
```

--------------------------------

### Install ghq with Scoop (Windows)

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Install ghq using the Scoop package manager on Windows.

```powershell
scoop install ghq

```

--------------------------------

### Logger Module Example

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Demonstrates how to use the Log and Logf functions with specific prefixes for logging clone operations and errors.

```go
logger.Log("clone", "https://github.com/x-motemen/ghq -> /home/user/ghq/github.com/x-motemen/ghq")
logger.Logf("error", "failed to clone: %v", err)
```

--------------------------------

### Install ghq with Guix (GNU Guix)

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Install ghq using the Guix package manager on GNU Guix.

```bash
guix install ghq

```

--------------------------------

### Example usage of isWorktreeGitDir

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/worktree-support.md

Provides examples of calling isWorktreeGitDir with paths that represent a worktree and a submodule.

```go
isWorktreeGitDir("/main/.git/worktrees/feature")  // true
isWorktreeGitDir("/main/.git/modules/submodule")  // false
```

--------------------------------

### ghq Repository Organization Example

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Illustrates the default directory structure for organizing repositories under `~/.ghq`.

```bash
~/.ghq/
├── github.com/
│   ├── x-motemen/
│   │   └── ghq/
│   └── golang/
│       └── go/
└── gitlab.com/
    └── user/
        └── project/
```

--------------------------------

### Install ghq with Homebrew (macOS)

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Install ghq using the Homebrew package manager on macOS.

```bash
brew install ghq

```

--------------------------------

### Subversion Clone Examples

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/vcs-backends.md

Demonstrates cloning SVN repositories with different layout detection and branch handling. Use for standard SVN repositories.

```bash
# Standard layout with trunk detection
svn checkout https://svn.example.com/proj/repo/trunk /path/to/repo
```

```bash
# Shallow checkout
svn checkout --depth immediates https://svn.example.com/proj/repo/trunk /path/to/repo
```

```bash
# Specific branch
svn checkout https://svn.example.com/proj/repo/branches/feature1 /path/to/repo
```

--------------------------------

### Install ghq with conda

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Install ghq using the conda package manager.

```bash
conda install -c conda-forge go-ghq

```

--------------------------------

### Implement get Method for getter in Go

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

The `get` method handles the initial cloning or updating of a repository. It parses the URL, extracts branch information, and delegates to `getRemoteRepository`.

```go
func (g *getter) get(ctx context.Context, argURL string) (getInfo, error)
```

--------------------------------

### Git-SVN Clone Examples

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/vcs-backends.md

Shows how to clone Git-SVN repositories, including options for standard layout detection and shallow clones. Use for repositories that bridge Git and SVN.

```bash
# Standard layout
git svn clone -s https://svn.example.com/proj/repo /path/to/repo
```

```bash
# Shallow clone
git svn clone -r100:HEAD https://svn.example.com/proj/repo /path/to/repo
```

```bash
# Specific branch
git svn clone https://svn.example.com/proj/repo/branches/feature1 /path/to/repo
```

--------------------------------

### Example ghq Configuration (.gitconfig)

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Configure custom VCS and root directories for specific repository URLs in your .gitconfig file.

```ini
[ghq "https://git.example.com/repos/"]
vcs = git
root = ~/myproj

```

--------------------------------

### Example usage of isLinkedGitDir

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/worktree-support.md

Demonstrates how to use isLinkedGitDir to check both worktree and regular repository directories.

```go
// Worktree directory
linked, target, _ := isLinkedGitDir("/path/to/worktree")
// linked = true
// target = "/path/to/main/.git/worktrees/wt1"

// Regular repository
linked, target, _ := isLinkedGitDir("/path/to/repo")
// linked = false
// target = ""
```

--------------------------------

### NewRemoteRepository Constructor Example

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Constructs a concrete RemoteRepository implementation based on the provided URL. Handles selection logic for various hosts and schemes.

```go
u, _ := url.Parse("https://github.com/x-motemen/ghq")
remote, err := NewRemoteRepository(u)
// remote is *GitHubRepository
```

--------------------------------

### Set Global Default Host Configuration

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

Example of setting the global ghq.defaultHost configuration using git config.

```bash
git config --global ghq.defaultHost gitlab.com
# Now: ghq get user/project
# Clones from: https://gitlab.com/user/project
```

--------------------------------

### Example VCS Detection for Unknown Hosts

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/vcs-backends.md

Demonstrates how ghq attempts to detect the VCS for repositories with custom hosts by executing commands like `git ls-remote` or `hg identify`.

```bash
# Unknown host - tested in order
ghq get https://custom-git-host.example.com/org/repo
# Tries: git ls-remote → success → uses Git

ghq get https://custom-vcs.example.com/org/repo
# Tries: git ls-remote → fail
# Tries: hg identify → success → uses Mercurial
```

--------------------------------

### Get Subpaths of Repository

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Returns a list of tail path components, ordered from shortest to longest.

```go
func (repo *LocalRepository) Subpaths() []string
```

```go
// Returns: ["ghq", "x-motemen/ghq", "github.com/x-motemen/ghq"]
```

--------------------------------

### Go Development Setup with ghq

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/configuration.md

Configure ghq to manage Go projects within $GOPATH/src while using a separate root for other repositories. This ensures Go packages are cloned to the correct location.

```bash
# Go requires repos in $GOPATH/src
git config --global ghq.root ~/.ghq
git config --global ghq.root $GOPATH/src

# Go packages clone to $GOPATH/src
ghq get github.com/golang/go
# Result: $GOPATH/src/github.com/golang/go

# Other repos clone to ~/.ghq
ghq get https://gitlab.com/user/project
# Result: ~/.ghq/gitlab.com/user/project
```

--------------------------------

### Relative Path Example

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

Demonstrates how ghq resolves a relative path to a full HTTPS URL based on the current directory and repository roots.

```bash
$ cd /home/user/ghq/github.com/x-motemen/ghq
$ ghq get ./something
# Resolves to: /home/user/ghq/github.com/x-motemen/ghq/something
# Becomes: https://github.com/x-motemen/ghq/something
```

--------------------------------

### Get VCS Backend and Root Path

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Retrieves the detected VCS backend and the repository root directory path. It searches candidate directories and caches the result.

```go
func (repo *LocalRepository) VCS() (*VCSBackend, string)
```

--------------------------------

### Clone a Repository with ghq

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Use `ghq get` to clone a repository. It creates the directory structure under `~/.ghq/`. Flags allow updating existing clones, using SSH, cloning specific branches, performing shallow clones, or opening a shell in the repository after cloning.

```go
ghq get https://github.com/x-motemen/ghq
// Creates: ~/.ghq/github.com/x-motemen/ghq
```

--------------------------------

### User Preference Setup for ghq

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/configuration.md

Configure user preferences for ghq, such as always using SSH for GitHub or customizing the default username for repository cloning. This simplifies common operations.

```bash
# Always use SSH for GitHub
git config --global github.user myusername
# Then use: ghq get -p myusername/project

# Auto-complete with same name (not username)
git config --global ghq.completeUser false
# ghq get ruby → ~/ghq/github.com/ruby/ruby

# Custom username
git config --global ghq.user customuser
# ghq get project → ~/ghq/github.com/customuser/project
```

--------------------------------

### Get Local Repository Roots (Go)

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Retrieves a list of root directories configured for ghq. Set `all` to true to include roots matched by git configuration, not just primary ones.

```go
func localRepositoryRoots(all bool) ([]string, error)
```

--------------------------------

### Get the ghq root directory

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Use `ghq root` to display the configured root directory for ghq. The `--all` option shows all configured root directories.

```bash
ghq root [--all]
```

--------------------------------

### GitHub Repository Path Truncation

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

Demonstrates how GitHub repository URLs are transformed by truncating the path to the first two components. This is an example of URL path transformation during VCS detection.

```go
// Input: https://github.com/x-motemen/ghq/blob/main/README.adoc
// Truncates to first 2 path components:
// Output: https://github.com/x-motemen/ghq

```

--------------------------------

### ghq create: Directory Exists and Not Empty Error

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/errors.md

This error is triggered when the target directory for a new repository already exists and contains files. To resolve this, either remove the existing directory first or use 'ghq get' to clone an existing repository.

```bash
error: directory "/home/user/ghq/github.com/user/repo" already exists and not empty
```

--------------------------------

### Clone a remote repository with ghq

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Use `ghq get` to clone a repository. If the repository already exists locally, this command will update it if the `-u` flag is provided. Use `-p` to clone via SSH. Supports shallow and bare clones for Git repositories.

```bash
ghq get https://github.com/x-motemen/ghq
```

--------------------------------

### Create LocalRepository from URL

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Constructs a LocalRepository from a remote URL. Searches for existing repositories or creates a new instance. Appends ".git" for bare repositories.

```go
func LocalRepositoryFromURL(remoteURL *url.URL, bare bool) (*LocalRepository, error)
```

```go
u, _ := url.Parse("https://github.com/x-motemen/ghq")
repo, err := LocalRepositoryFromURL(u, false)
// repo.FullPath = "/home/user/ghq/github.com/x-motemen/ghq"
// repo.RelPath = "github.com/x-motemen/ghq"
```

--------------------------------

### Build ghq from source

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Clone the repository and build ghq from source using make.

```bash
git clone https://github.com/x-motemen/ghq .
make install

```

--------------------------------

### Error: Failed to Get Remote URL

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/errors.md

This error indicates that ghq could not retrieve the remote URL for the repository. This can happen if no remote is configured, the VCS backend does not support remote URL retrieval, or the command to get the URL fails.

```text
error: failed to get remote URL: git: no remote configured
```

--------------------------------

### Print All Configured Repository Roots

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-commands.md

Use the `--all` flag to display all configured repository root directories for ghq. This includes primary and any additional roots defined in the configuration.

```bash
ghq root --all
```

--------------------------------

### Detect shell for ghq get --look command

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/configuration.md

This Go code snippet illustrates how ghq detects the user's shell for the `ghq get --look` command. It prioritizes the SHELL environment variable (Unix) or COMSPEC (Windows), falling back to /bin/sh.

```go
shell := os.Getenv("SHELL")
if shell != "" {
    return shell
}
if runtime.GOOS == "windows" {
    return os.Getenv("COMSPEC")
}
return "/bin/sh"
```

--------------------------------

### Create LocalRepository from Full Path

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Constructs a LocalRepository using an absolute path. It determines the root directory and computes the relative path.

```go
func LocalRepositoryFromFullPath(fullPath string, backend *VCSBackend) (*LocalRepository, error)
```

```go
repo, err := LocalRepositoryFromFullPath("/home/user/ghq/github.com/x-motemen/ghq", nil)
// repo.RelPath = "github.com/x-motemen/ghq"
```

--------------------------------

### Get Path Excluding Hostname

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Returns the repository path components, omitting the hostname.

```go
func (repo *LocalRepository) NonHostPath() string
```

--------------------------------

### Get Pijul Remote URL

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/vcs-backends.md

Retrieves the first remote URL for a Pijul repository.

```bash
pijul remote
```

--------------------------------

### Get Mercurial Remote URL

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/vcs-backends.md

Retrieves the default remote repository URL for a Mercurial repository.

```bash
hg paths default
```

--------------------------------

### Create New Repository with ghq

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Use `ghq create` to initialize a new repository directory structure. It also performs a VCS-specific initialization, like `git init`.

```go
ghq create github.com/user/newrepo
// Creates empty repository directory structure
// Initializes with: git init (or other VCS init)
```

--------------------------------

### Create a new repository with ghq

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Use `ghq create` to initialize a new repository. This command supports specifying the Version Control System (VCS) to use.

```bash
ghq create --vcs <vcs> <repository URL>|<host>/<user>/<project>|<user>/<project>|<project>
```

--------------------------------

### Create New Repository

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-commands.md

Use this command to create a new, empty repository within the ghq structure. It initializes the VCS backend automatically.

```bash
ghq create github.com/username/newrepo
```

```bash
ghq create --vcs git github.com/username/newrepo
```

```bash
ghq create --bare github.com/username/newrepo.git
```

--------------------------------

### Get Repository Root Path

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Retrieves the repository root path, which might differ from FullPath for nested structures.

```go
func (repo *LocalRepository) RepoPath() string
```

--------------------------------

### Get Darcs Remote URL

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/vcs-backends.md

Retrieves the default remote repository URL for a Darcs repository by parsing its info.

```bash
darcs show repo
```

--------------------------------

### List All Repositories with ghq

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-commands.md

Use this command to list all locally cloned repositories. No additional flags or arguments are needed for a basic listing.

```bash
ghq list
```

--------------------------------

### SCP-like URLs

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

SCP-like URLs are detected and transformed into SSH URLs. Paths not starting with '/' are treated as absolute.

```text
github.com:x-motemen/ghq
git@github.com:x-motemen/ghq
user@git.example.com:path/to/repo
```

--------------------------------

### Build all ghq packages

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Execute 'go build ./...' to compile all packages within the ghq project. This is useful for ensuring all components are built correctly.

```bash
go build ./...     # Build all packages
```

--------------------------------

### Get Boolean Configuration Value

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/configuration.md

Retrieve the boolean value of a ghq configuration option programmatically using the gitconfig library.

```go
completeUser, err := gitconfig.Bool("ghq.completeUser")
```

--------------------------------

### List Repositories with ghq

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Use `ghq list` to display repositories. Options include filtering by name, exact matching, showing full paths, deduplicating entries, and specifying multiple roots.

```go
ghq list                          // All repositories
ghq list motemen                  // Partial match
ghq list -e motemen/ghq           // Exact match
ghq list -p                       // Full paths
ghq list --unique                 // Deduplicated (multi-root)
```

--------------------------------

### Get Git Remote URL

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/vcs-backends.md

Retrieves the URL of the 'origin' remote repository. Falls back to the first remote if 'origin' is not found.

```bash
# From repository
git remote get-url origin
# Output: https://github.com/x-motemen/ghq
```

--------------------------------

### ghq create: Unsupported VCS Initialization Error

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/errors.md

This error indicates that the specified Version Control System (VCS) does not support repository initialization or is not recognized. Use one of the supported VCS backends like git, hg, svn, etc.

```bash
error: failed to init: unsupported VCS
```

--------------------------------

### ghq Command Handlers

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

These functions handle the core logic for each ghq command, such as get, list, create, rm, migrate, and root.

```go
func doGet(ctx context.Context, cmd *cli.Command) error
func doList(ctx context.Context, cmd *cli.Command) error
func doCreate(ctx context.Context, cmd *cli.Command) error
func doRm(ctx context.Context, cmd *cli.Command) error
func doMigrate(ctx context.Context, cmd *cli.Command) error
func doRoot(ctx context.Context, cmd *cli.Command) error
```

--------------------------------

### Custom VCS Backend Template

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/vcs-backends.md

Implement a new VCS backend by defining Clone, Update, Init, Contents, and RemoteURL functions. Add the new backend to the `vcsRegistry` map.

```go
var CustomBackend = &VCSBackend{
    Clone: func(vg *vcsGetOption) error {
        args := []string{"clone"}
        // Add options
        args = append(args, vg.url.String(), vg.dir)
        return run(vg.silent)("custom-vcs", args...)
    },
    Update: func(vg *vcsGetOption) error {
        return runInDir(vg.silent)(vg.dir, "custom-vcs", "update")
    },
    Init: func(dir string) error {
        return cmdutil.RunInDir(dir, "custom-vcs", "init")
    },
    Contents: []string{".custom"},
    RemoteURL: func(dir string) (string, error) {
        cmd := exec.Command("custom-vcs", "info")
        cmd.Dir = dir
        output, err := cmd.Output()
        // Parse and return remote URL
    },
}
```

--------------------------------

### ghq Main Application Entry Point

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

The `main` function serves as the entry point for the ghq application. `newApp` is used to construct the CLI application.

```go
func main()                    // Entry point
func newApp() *cli.Command     // Create CLI app
```

--------------------------------

### Walk All Local Repositories (Go)

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Use this function to iterate over all local repositories configured in ghq. It accepts a callback function that will be executed for each repository found.

```go
func walkAllLocalRepositories(callback func(*LocalRepository)) error
```

--------------------------------

### List Full Paths with ghq

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-commands.md

Display the full paths of cloned repositories instead of their relative paths. Use the `-p` or `--full-path` flag for this output format.

```bash
ghq list -p
```

--------------------------------

### ghq get

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-commands.md

Clones or updates a remote repository to the ghq root directory. Supports various options for controlling the clone process, protocol, and post-clone actions.

```APIDOC
## ghq get

### Description
Clones or updates a remote repository to the ghq root directory. Supports various options for controlling the clone process, protocol, and post-clone actions.

### Flags

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--update` | `-u` | bool | false | Update local repository if already cloned |
| `--p` | (none) | bool | false | Clone via SSH protocol |
| `--shallow` | (none) | bool | false | Perform shallow clone (Git only) |
| `--look` | `-l` | bool | false | Open shell in repository after clone |
| `--vcs` | (none) | string | auto-detect | Specify VCS backend (git, svn, hg, etc.) |
| `--silent` | `-s` | bool | false | Suppress logging output |
| `--no-recursive` | (none) | bool | false | Prevent recursive submodule fetching |
| `--branch` | `-b` | string | empty | Clone specific branch (implies --single-branch for Git) |
| `--parallel` | `-P` | bool | false | Import multiple repositories in parallel |
| `--bare` | (none) | bool | false | Perform bare clone (Git only) |
| `--partial` | (none) | enum | empty | Partial clone mode: "blobless" or "treeless" (Git only) |

### Example Usage
```bash
# Command line:
ghq get https://github.com/x-motemen/ghq

# With options:
ghq get -u -p --branch main https://github.com/x-motemen/ghq
ghq get --parallel < repositories.txt
```
```

--------------------------------

### Invalid CodeCommit Region

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

Demonstrates an error when an invalid AWS CodeCommit region is provided in the URL. The region must start with a letter and contain only alphanumerics and hyphens.

```bash
codecommit::invalid region://user/repo
// Error: region must start with letter and contain only alphanumerics/hyphens
```

--------------------------------

### Shorthand User/Project Format

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

Two-part shorthand formats (<user>/<project>) are resolved by prepending the default host and potentially detecting the username.

```text
x-motemen/ghq
golang/go
rails/rails
```

--------------------------------

### Go Type Annotations

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/INDEX.md

Illustrates common Go type annotations used for function signatures and type definitions. These are standard Go syntax.

```go
func Name(param Type) Type
func (receiver Type) Method(param Type) Type
type TypeName struct { }
type InterfaceName interface { }
```

--------------------------------

### Walk Local Repositories by VCS (Go)

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

This function allows walking through local repositories, filtering them by a specific Version Control System (VCS) name. Provide the VCS name and a callback function to process each matching repository.

```go
func walkLocalRepositories(vcs string, callback func(*LocalRepository)) error
```

--------------------------------

### Preview Repository Migration

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-commands.md

Use the `--dry-run` flag to see what would happen during a repository migration without actually performing any changes. This is useful for verifying the migration process.

```bash
ghq migrate --dry-run /home/user/my-old-repo
```

--------------------------------

### DarcsBackend Definition

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Represents the Darcs version control system backend. It uses 'darcs get --lazy' for cloning and 'darcs pull' for updates, with '_darcs' as the VCS specific content.

```go
var DarcsBackend = &VCSBackend{ ... }
```

--------------------------------

### Relative Path Step 1: Clean and Join Path

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

Cleans and joins the relative path with the current working directory.

```go
path := filepath.Clean(filepath.Join(wd, ...parts))
```

--------------------------------

### ghq Get URL Parsing Error

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/errors.md

This error indicates that the provided URL could not be parsed by ghq. Check for invalid URL syntax, unresolvable relative paths, or malformed URLs.

```bash
$ ghq get "https://[invalid"
error: could not parse URL "https://[invalid": parse "https://[invalid": net.SplitHostPort: too many colons in address
```

--------------------------------

### List local repositories with ghq

Source: https://github.com/x-motemen/ghq/blob/master/README.adoc

Use `ghq list` to display locally cloned repositories. You can filter the list by providing a query string. The `-e` flag enables exact matching, and `-p` prints the full path to the repository.

```bash
ghq list
```

--------------------------------

### ghq Core Types: Getter

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

The `getter` struct and its methods are responsible for fetching repository information. `get` fetches general info, while `getRemoteRepository` fetches specific remote repository details.

```go
type getter struct { ... }
func (g *getter) get(ctx context.Context, argURL string) (getInfo, error)
func (g *getter) getRemoteRepository(ctx context.Context, remote RemoteRepository, branch string) (getInfo, error)
```

--------------------------------

### Create Root CLI Application

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-commands.md

Defines the root command for the ghq CLI application, setting its name, usage, version, authors, and subcommands. Use this to initialize the application structure.

```go
func newApp() *cli.Command {
    return &cli.Command{
        Name:     "ghq",
        Usage:    "Manage remote repository clones",
        Version:  fmt.Sprintf("%s (rev:%s)", version, revision),
        Authors:  []any{"motemen <motemen@gmail.com>", "Songmu <y.songmu@gmail.com>"},
        Suggest:  true,
        Commands: commands,
    }
}
```

--------------------------------

### ghq Get Clone Failure

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/errors.md

This error signifies a failure during the cloning or updating process of a repository. It can be caused by VCS command failures, directory issues, network problems, permissions, or disk space limitations.

```bash
$ ghq get https://github.com/nonexistent/repo
error: failed to get "https://github.com/nonexistent/repo": git: failed to clone repository
```

--------------------------------

### RemoteRepository Interface Definition

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/types.md

Defines the interface for remote repositories, specifying methods to retrieve the URL, check validity, and get VCS information. This allows ghq to interact with various repository hosting services.

```go
type RemoteRepository interface {
    URL() *url.URL
    IsValid() bool
    VCS() (*VCSBackend, *url.URL, error)
}
```

--------------------------------

### ghq Multiple Roots Configuration

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Shows how to configure multiple root directories for ghq. The last listed root is considered primary for new clones.

```bash
ghq.root = ~/.ghq         # Primary (new clones here)
ghq.root = $GOPATH/src    # Secondary (Go packages)
```

--------------------------------

### ghq Get URL Parsing Error

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/errors.md

This error occurs when the provided repository path is not valid according to ghq's parsing rules. Ensure the path has the correct number of components for the specified repository host.

```bash
$ ghq get github.com/user
error: not a valid repository: https://github.com/user
```

--------------------------------

### Find VCS Backend (Go)

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Detects the Version Control System (VCS) backend for a given file path. Optionally, you can specify a VCS name to restrict the search. It prioritizes VCS content markers like .git or .hg.

```go
func findVCSBackend(fpath, vcs string) *VCSBackend
```

--------------------------------

### Set GHQ_ROOT for multiple repository paths (Unix)

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/configuration.md

Override all configured roots with a single directory or a colon-separated list of directories. When set, all other ghq.root configurations are ignored. This example shows setting multiple paths for the current session.

```bash
# Use /opt/repos for this session only
export GHQ_ROOT=/opt/repos
ghq list

# Multiple paths (Unix)
export GHQ_ROOT=~/.ghq:/opt/repos
ghq list
```

--------------------------------

### LocalRepositoryFromURL

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Constructs a LocalRepository from a remote URL. It searches for existing local repositories or creates a new instance based on the URL and bare repository status.

```APIDOC
## LocalRepositoryFromURL

### Description
Constructs a `LocalRepository` from a remote URL. It searches for existing local repositories or creates a new instance based on the URL and bare repository status.

### Method
`func LocalRepositoryFromURL(remoteURL *url.URL, bare bool) (*LocalRepository, error)`

### Parameters
#### Path Parameters
- `remoteURL` (*url.URL) - Required - Parsed remote repository URL
- `bare` (bool) - Required - If true, appends ".git" to path (for bare repositories)

### Returns
- `*LocalRepository` - Constructed `LocalRepository` instance.
- `error` - An error if the repository could not be constructed.

### Behavior
1. Searches existing local repositories for matching `RelPath`
2. If not found, determines root using `getRoot()` and creates new instance
3. For bare repositories, appends ".git" to repository name

### Example
```go
u, _ := url.Parse("https://github.com/x-motemen/ghq")
repo, err := LocalRepositoryFromURL(u, false)
// repo.FullPath = "/home/user/ghq/github.com/x-motemen/ghq"
// repo.RelPath = "github.com/x-motemen/ghq"
```
```

--------------------------------

### ghq Get VCS Detection Failure

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/errors.md

This error occurs when ghq cannot determine the Version Control System (VCS) for a local repository. This usually happens if the repository lacks standard VCS markers (like .git) or if VCS detection fails.

```bash
error: failed to detect VCS for "/home/user/ghq/example.com/repo"
```

--------------------------------

### Configure Multiple Repository Roots

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/configuration.md

Define multiple directories for ghq to store repositories. The last configured root becomes the primary one for new clones.

```bash
# Single root
git config --global ghq.root ~/.ghq

# Multiple roots (e.g., for Go projects)
git config --global ghq.root ~/.ghq
git config --global ghq.root ~/go/src

# Primary root becomes the last configured
# New repos clone to ~/go/src
```

--------------------------------

### LocalRepositoryFromFullPath

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Constructs a LocalRepository from an absolute local path. It determines the repository root and computes the relative path.

```APIDOC
## LocalRepositoryFromFullPath

### Description
Constructs a `LocalRepository` from an absolute local path. It determines the repository root and computes the relative path.

### Method
`func LocalRepositoryFromFullPath(fullPath string, backend *VCSBackend) (*LocalRepository, error)`

### Parameters
#### Path Parameters
- `fullPath` (string) - Required - Absolute path to repository directory
- `backend` (*VCSBackend) - Optional - Detected VCS backend (can be nil)

### Returns
- `*LocalRepository` - Constructed `LocalRepository` instance.
- `error` - An error if the repository could not be constructed.

### Behavior
1. Finds root directory containing the path
2. Computes relative path from root
3. Splits relative path into components

### Example
```go
repo, err := LocalRepositoryFromFullPath("/home/user/ghq/github.com/x-motemen/ghq", nil)
// repo.RelPath = "github.com/x-motemen/ghq"
```
```

--------------------------------

### Configuring Multiple Roots for ghq

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/configuration.md

Set multiple root directories for ghq. The primary root is used for new clones, and 'ghq list' will show repositories from all configured roots.

```bash
git config --global ghq.root ~/.ghq
git config --global ghq.root ~/go/src

# Primary root for new clones
ghq root  # Shows ~/go/src (primary)
ghq root --all  # Shows both

# New repos clone to ~/go/src
ghq get github.com/golang/go
# Result: ~/go/src/github.com/golang/go

# Existing repos found in either root
ghq list
```

--------------------------------

### Configure Default Host for URL Resolution

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

Resolves the host for a URL, prioritizing the 'ghq.defaultHost' Git configuration. If the configuration is not found or empty, it defaults to 'github.com'.

```go
host, err := gitconfig.Get("ghq.defaultHost")
if (err != nil && !gitconfig.IsNotFound(err)) || host != "" {
    u.Host = host
} else {
    u.Host = "github.com"
}
```

--------------------------------

### walkAllLocalRepositories

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Walks all local repositories across all configured roots, calling a callback function for each found repository.

```APIDOC
## walkAllLocalRepositories

### Description
Walks all local repositories across all configured roots, calling callback for each found.

### Signature
```go
func walkAllLocalRepositories(callback func(*LocalRepository)) error
```
```

--------------------------------

### Clone Fossil Repository

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/vcs-backends.md

Use this command to clone a Fossil repository. It requires creating a directory, cloning the repository into a .fossil file, and then opening the checkout.

```bash
# Basic clone
fossil clone https://fossil-scm.org/home /path/to/repo/.fossil
cd /path/to/repo && fossil open .fossil
```

--------------------------------

### Find Repository Root with ghq

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Use `ghq root` to find the root directory of your repositories. The `--all` flag lists all configured roots.

```go
ghq root                          // Primary root
ghq root --all                    // All configured roots
```

--------------------------------

### cmdutil Module Functions

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Offers utilities for executing external VCS commands. Functions include options for silent execution and running commands within a specified directory.

```go
func Run(command string, args ...string) error
func RunSilently(command string, args ...string) error
func RunInDir(dir, command string, args ...string) error
func RunInDirSilently(dir, command string, args ...string) error
func RunCommand(cmd *exec.Cmd, silent bool) error
```

--------------------------------

### Relative Path Step 3: Build HTTPS URL

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

Constructs the final HTTPS URL from the matched relative path.

```go
ref = "https://" + localRepoRoot
```

--------------------------------

### FossilBackend Definition

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Represents the Fossil version control system backend. It uses 'fossil clone' and 'fossil open' for cloning and 'fossil update' for updates, with '.fslckout' and '_FOSSIL_' as VCS specific content.

```go
var FossilBackend = &VCSBackend{ ... }
```

--------------------------------

### PijulBackend Definition

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-core.md

Represents the Pijul version control system backend. It uses 'pijul clone --channel <branch>' for cloning and 'pijul pull' for updates, with '.pijul' as the VCS specific content.

```go
var PijulBackend = &VCSBackend{ ... }
```

--------------------------------

### ghq migrate: Directory Does Not Exist Error

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/errors.md

This error indicates that the provided directory path for migration does not exist. Verify that the path is correct and that the directory exists.

```bash
error: directory "/path/to/missing/repo" does not exist
```

--------------------------------

### Specify VCS Backend for URL Match

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/configuration.md

Explicitly define the Version Control System (VCS) for repositories matching a specific URL pattern. Supports various VCS types.

```bash
# Specify VCS for all repos under example.com
git config --global ghq.https://git.example.com/.vcs git

# Set subversion for specific path
git config --global ghq.https://svn.example.com/repos/.vcs subversion
```

--------------------------------

### ghq Core Types: LocalRepository

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Defines the `LocalRepository` struct and functions to create it from a URL or a full path.

```go
type LocalRepository struct { ... }
func LocalRepositoryFromURL(remoteURL *url.URL, bare bool) (*LocalRepository, error)
func LocalRepositoryFromFullPath(fullPath string, backend *VCSBackend) (*LocalRepository, error)
```

--------------------------------

### Migrate Repository with Confirmation

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/api-reference-commands.md

Use this command to migrate an existing repository to the ghq-managed directory structure. The command will prompt for confirmation before proceeding.

```bash
ghq migrate /home/user/my-old-repo
```

--------------------------------

### Basic Git Clone

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/vcs-backends.md

Performs a basic clone of a Git repository to a specified directory.

```bash
# Basic clone
git clone https://github.com/x-motemen/ghq /path/to/ghq
```

--------------------------------

### Error: Failed to Detect VCS Backend

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/errors.md

This error occurs when ghq cannot find any version control system markers (like .git, .hg, .svn) in the specified directory. Ensure the directory is a valid VCS repository.

```text
error: failed to detect VCS backend in "/path/to/repo"
```

--------------------------------

### Project Only Format Behavior Determination

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

Determines whether to use 'project/project' or 'username/project' format based on the 'ghq.completeUser' git configuration.

```go
completeUser, err := gitconfig.Bool("ghq.completeUser")
if err == nil && !completeUser {
    // Use project/project format
    return path + "/" + path
}
// Use username/project format
user := detectUserName()
return user + "/" + path
```

--------------------------------

### Shorthand Project Only Format

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/url-parsing.md

One-part shorthand formats (<project>) are processed by fillUsernameToPath to prepend a username or project name, then treated as a two-part format.

```text
ghq
node
rails
```

--------------------------------

### ghq Logging Utilities

Source: https://github.com/x-motemen/ghq/blob/master/_autodocs/README.md

Offers functions for logging messages with prefixes, formatted logging, and setting the output destination for logs.

```go
func Log(prefix, message string)
func Logf(prefix, msg string, args ...any)
func SetOutput(w io.Writer)
```
Tokens:
Raw