gitserver API

As of February 1, 2023

gitserver is Sourcegraph's interface to Git repositories. It clones repositories and exposes an API for interacting with that clone.

gitserver used to expose a simple "run any Git command" interface, but that was removed and in its place the gitserver client exposes an API supporting specific Git operations.

Method Description Notes Git Command or GitServer Endpoint
AddrForRepo resolves repo names to gitserver instances
Addrs returns addresses for gitserver instances
ArchiveReader download archived repository
BatchLog allows for monitoring and aborting the applying of batch changes git log -n 1 --name-only
BlameFile returns git blame information about a file git blame
StreamBlameFile Same as BlameFile, but streaming git blame
BranchesContaining Returns all of the branches containing the given commit git branch --contains <commit> --format %(refname)
CommitDate returns the time the given commit was committed Does not error if commit DNE, but returns a false value flag git show -s --format=%H:%cI
CommitExists determines if the given commit exists in the given repository Does not error if commit DNE, but returns a false value flag git log --format=format:%H%x00%aN%x00%aE%x00%at%x00%cN%x00%cE%x00%ct%x00%B%x00%P%x00 -n 1 <commit hash>
CommitGraph returns the commit graph for the given repository as a mapping from a commit to its parents runs git log --pretty="%H %P" --topo-order with either --all --since, or -### with a numeric limit
Commits returns all commits matching the options runs git log --pretty="%H %P" --topo-order with either --all --since, or -### with a numeric limit, and filters them based on supplied options, such as author, message, before, after, etc...
CommitsExist determines if the given commits exist in the given repositories Uses GetCommits
CommitsUniqueToBranch returns a map from commits that exist on a given branch in the given repository to their commit date runs git log --pretty=format:%H:%cI with other options depending on parameters
ContributorCount returns the number of commits grouped by contributor runs git shortlog -s -n -e --no-merges with other options depending on parameters
CreateCommitFromPatch Creates a commit from a patch file (optionally pushing it to origin?) clones the repo to a temp dir, then runs git apply on the patch.
Diff returns an iterator that can be used to access the diff between two commits on a per-file basis comment on the method mentions go-diff which might be useful to look into git diff --find-renames --full-index --inter-hunk-context=3 --no-prefix <range> --
DiffPath returns the changes to a given path between the given source and target commits returns one diff even if there are multiple commits in between the two given commits git diff <from commit> <to commit> -- <path>
DiffSymbols performs a diff command which is expected to be parsed by our symbols package git diff -z --name-status --no-renames <from commit> <to commit>
FirstEverCommit returns the first commit ever made to the repository runs git rev-list --reverse --date-order --max-parents=0 HEAD to get the commit hash, then calls GetCommit with the hash
GetBehindAhead returns the behind/ahead commit counts information for right vs. left (both Git revspecs) git rev-list --count --left-right <left commit>...<right commit>
GetCommit returns the commit with the given commit ID errors if no such commit exists git log -n 1 <commit>
GetCommits returns a git commit object describing each of the given repository and commit pairs Uses the batch log interface git log -n 1 --name-only
GetDefaultBranch Returns the default branch name and current commit "default" means "current" in the implementation, probably because all of the indexing work in a repository is done in the default branch? git symbolic-ref HEAD
GetObject Returns a Git Object, which is one of "commit", "tag", "tree" or "blob" I'm not clear on the use cases for this method uses git rev-parse and git cat-file
HasCommitAfter returns a boolean indicating if a repo contains a commit after a given date. Used to assess how "stale" a repository is Does it look at the origin? Just locally? git rev-list -n 1 --after=<date> --count HEAD
Head determines the tip commit of the default branch for the given repository runs git rev-parse HEAD to get the commit hash, then uses GetCommit
IsRepoCloneable returns an error if a repo is not cloneable
ListBranches Returns a list of all of the branches in the repository Includes information about the HEAD commit, and how many commits the branch is beind and ahead of another given branch. git branch
ListDirectoryChildren fetches the list of children under the given directory names Seems to be NOT recursive? Returns strings, not Git Objects. git ls-tree --name-only <commit id> -- <dirname> ...
ListFiles returns a list of root-relative file paths matching the given pattern in a particular commit of a repository This one is recursive - uses the -r option. git ls-tree --name-only -r <commit id> -- and then filtering returned paths by a given regular expression
ListRefs Returns a list of references in a repository references are human-friendly names for commit hashes. For example, git checkout -b mybranch creates a reference named "mybranch" pointed to the current HEAD hash. References are files stored in .git/refs. What's the use case for this? Is it mainly/only for display so an end user can click on a particular reference and will be taken to that target? git show-ref
ListTags returns a list of all tags in the repository. If commitObjs is non-empty, only all tags pointing at those commits are returned. git tag --list --sort --creatordate --format %(if)%(\*objectname)%(then)%(\*objectname)%(else)%(objectname)%(end)%00%(refname:short)%00%(if)%(creatordate:unix)%(then)%(creatordate:unix)%(else)%(\*creatordate:unix)%(end)
LsFiles returns the output of git ls-files, null-separated, with optional path specifications git ls-files -z --with-tree <commit id> -- <path> ...
MergeBase returns the common ancestor for a merge of two given commits git merge-base
NewFileReader reads from the given file at the given commit git show <commit>:<path>
P4Exec sends a p4 command and reads the output Accesses the /p4-exec endpoint of gitserver, which according to the comments, "is currently only used for fetching user based permissions information so, we don't have a repo name" Doesn't do any Git commands; runs p4 with the given command
ReadDir reads the given directory at the given commit the comment on --long is, "show size" git ls-tree --long --full-name -z <commit> (-r -t)? (-- <path>)?
ReadFile Like NewFileReader, but returns a byte slize instead of a reader uses NewFileReader internally git show <commit>:<path>
RefDescriptions returns a map from commits to descriptions of the tip of each branch and tag of the given repository returns the struct:
\- the name of the branch/tag
\- the type (unknown, branch, or tag)
\- true/false for default (current) branch
\- date branch/tag created
git for-each-ref --format="%(if)%(\*objectname)%(then)%(\*objectname)%(else)%(objectname)%(end)%(refname)%(HEAD)%(if)%(\*creatordate:iso8601-strict)%(then)%(\*creatordate:iso8601-strict)%(else)%(creatordate:iso8601-strict)%(end)%00" refs/heads/ refs/tags/ --points-at=<commit>
Remove removes the repository clone from gitserver looks up the instance and calls RemoveFrom with that instance
RemoveFrom removes the repository clone from the given gitserver
RepoCloneProgress calls gitserver's /repo-clone-progress endpoint Returns the output of the clone command checks on the existance of GIT_DIR and if it's still locked by a clone process
ReposStats returns statistics for each gitserver calls gitserver's /repos-stats endpoint, which returns the contents of the file repos-stats.json
RequestRepoClone an asynchronous request to clone a repository calls gitserver's /repo-clone endpoint git clone
RequestRepoUpdate calls gitserver's /repo-update endpoint
ResolveRevision returns the absolute commit for a commit-ish spec git rev-parse <commit-ish spec>
ResolveRevisions expands a set of RevisionSpecifiers (which may include hashes, globs, refs, or glob exclusions) into an equivalent set of commit hashes git rev-parse <commit-ish spec> ...
Stat returns a FileInfo describing the named file at commit maps output from git ls-tree into FileInfo structs, with the object hash in the Sys_ member