Repository management and browse

Active contributors: Mislav, Sam Coe, vilmibm

Purpose

gh repo is the second-largest command tree (21 subdirectories). It covers the lifecycle of a repository as seen from the CLI: clone, create, view, edit, fork, sync, archive, rename, set-default, deploy keys, autolinks, license, and .gitignore templates. gh browse opens repository URLs in the user's browser.

Directory layout

pkg/cmd/repo/
  repo.go            # NewCmdRepo: registers subcommands
  clone/  create/  view/  list/  edit/  fork/  sync/
  rename/  archive/  unarchive/  delete/  setdefault/
  deploy-key/{add,delete,list}
  autolink/{create,delete,list,view}
  gitignore/{list,view}
  license/{list,view}
  credits/         # community credits
  garden/          # easter-egg ASCII garden visualisation
  shared/          # shared helpers (clone resolution, owner prompting)

pkg/cmd/browse/
  browse.go        # gh browse <number|path>

Key abstractions

Symbol	File	Role
NewCmdRepo	pkg/cmd/repo/repo.go	Subcommand registration.
cloneRun	pkg/cmd/repo/clone/clone.go	Resolves the canonical repo, sets remotes (origin + upstream when forking), invokes git clone.
createRun	pkg/cmd/repo/create/create.go	Creates from scratch, from a template, or from an existing local repo.
forkRun	pkg/cmd/repo/fork/fork.go	Forks a repository and rewires git remotes.
syncRun	pkg/cmd/repo/sync/sync.go	Sync a fork or local branch with upstream.
setdefaultRun	pkg/cmd/repo/setdefault/setdefault.go	Writes the resolved git config key consumed by the smart repo resolver.
browseRun	pkg/cmd/browse/browse.go	Maps gh browse 123, gh browse <path>, etc. to a URL via internal/browser.

How it works

gh repo clone <owner/repo>:

1. The smart base repo resolver picks the target.
2. cloneRun resolves the upstream parent if the target is a fork (so git clone adds it as an upstream remote).
3. The HTTP/SSH URL is chosen based on git_protocol config.
4. git.Client.Clone shells out to git.

gh browse 123 works similarly: if the argument is numeric, it tries to interpret it as an issue or PR number; if it looks like a path, it constructs a tree/<branch>/<path> URL; with -c <commit> it points to a commit. The smart resolver provides the base repo.

Integration points

• Heavy users of git.Client: clone, fetch, set-remote, set-config, status.
• Use the smart base repo resolver, which is why fork-of-fork scenarios behave intuitively.
• Templates (gh repo create --template, gh repo gitignore, gh repo license) come from API endpoints under api/queries_repo.go.
• repo set-default writes the resolved config key that downstream commands read; this is the canonical way to disambiguate multiple remotes.

Entry points for modification

• New repo subcommand: add pkg/cmd/repo/<name>/<name>.go, register in repo.go. Keep server logic in http.go if it grows beyond a few queries.
• New browse URL pattern: extend the parsing logic in browse.go and add a row to the table-driven test.
• Changing remote semantics: most behaviour is in pkg/cmd/factory/remote_resolver.go and pkg/cmd/factory/default.go (SmartBaseRepoFunc).

Key source files

File	Purpose
pkg/cmd/repo/repo.go	Subcommand registration.
pkg/cmd/repo/clone/clone.go	Clone with fork-aware remote setup.
pkg/cmd/repo/create/create.go	Create-from-scratch, from-template, from-local.
pkg/cmd/repo/fork/fork.go	Fork + rewire remotes.
pkg/cmd/repo/sync/sync.go	Fork sync via API or local fast-forward.
pkg/cmd/repo/setdefault/setdefault.go	Defines the resolved key behaviour.
pkg/cmd/browse/browse.go	URL builder for gh browse.
git/client.go	The git executable wrapper (29 KB).

Related pages

• Git client.
• Factory and cmdutil for SmartBaseRepoFunc.
• API client.