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 removedand 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 | ||
LFSSmudge |
returns a reader of the contents from LFS of the LFS pointer at the given path. If the path is not an LFS pointer (contents more than 200 bytes), the contents of the given path are returned instead | Assuming the use of this method is to stream a binary file. | git lfs smudge <path> |
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 |