Git client

Active contributors: Mislav, William Martin, Tyler McGoffin

Purpose

git/ is the wrapper around the user's local git executable. Every CLI command that reads or writes the current repository goes through git.Client. The wrapper handles argument escaping, SSH/HTTPS protocol resolution, error normalisation, and per-command timeouts.

Directory layout

git/
  client.go                # ~29 KB: the Client type and ~50 methods
  command.go               # Command and CommandContext helpers
  errors.go                # Typed errors (ErrNotOnAnyBranch, GitError, ...)
  objects.go               # Commit, RemoteSet, Ref, Status, ...
  url.go                   # URL parsing (HTTPS, SSH-style, scp-style)
  fixtures/                # Pre-baked git directories for tests

Key abstractions

Symbol	File	Role
Client	client.go	The wrapper. Holds RepoDir, GhPath, Stderr, Stdin, Stdout, and shells out via cli/safeexec.
Client.Remotes()	client.go	Returns the repo's remotes, parsed into typed Remote objects.
Client.CurrentBranch / BranchCommit / Status / Push / Pull / Clone / Fetch / Checkout / Show	client.go	The standard surface used by commands.
Client.SetRemoteResolution	client.go	Writes the resolved git config key consumed by the smart base repo resolver.
Remote, RemoteURL, Ref, Commit, Status	objects.go	Typed git objects.
ParseURL	url.go	Accepts https://, ssh://, and git@host:owner/repo style URLs.
Error types	errors.go	ErrNotOnAnyBranch, GitError (preserves stderr).

How it works

graph TD
    A[Command] --> B[git.Client]
    B --> C[safeexec.LookPath git]
    C --> D[exec.Cmd with normalised args]
    D --> E[git executable]
    E --> F[stdout / stderr]
    F --> G[parser]
    G --> H[typed object back to command]

Outgoing args are always passed via []string (never built with fmt.Sprintf) to avoid shell injection. The wrapper sets GIT_* environment variables when needed (e.g. for SSH key or terminal-prompt settings) and surfaces non-zero exits as GitError with stderr attached.

Integration points

• Constructed by factory.newGitClient in pkg/cmd/factory/default.go. Pinned to f.IOStreams for stderr/stdin.
• Heavily used by pkg/cmd/repo/, pkg/cmd/pr/, pkg/cmd/issue/, pkg/cmd/auth/setupgit/, and the smart resolver.
• For tests, the fixtures/ directory contains pre-baked git directories; tests typically t.TempDir() and copy or git init a fresh repo as needed.

Entry points for modification

• New git operation: add a method to Client and unit tests in client_test.go (~65 KB). Stick to typed return values, not raw strings.
• New URL form: extend url.go and update the table-driven test in url_test.go.
• New error case: extend errors.go so callers can errors.As.

Key source files

File	Purpose
git/client.go	The Client type.
git/command.go	Helper for building exec commands.
git/objects.go	Domain objects.
git/url.go	URL parsing.
git/errors.go	Typed errors.

Related pages

• Repository management.
• Factory and cmdutil for SmartBaseRepoFunc.