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 |
|
BehindAhead |
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 |
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 |
|
IsPerforcePathCloneable |
check if a given depot/depot path is cloneable with the given credentials | calls gitserver's /is-perforce-path-cloneable endpoint |
|
CheckPerforceCredentials |
check if a given Perforce credential is valid | calls gitserver's /check-perforce-credentials endpoint |
|
PerforceUsers |
list all perforce users | calls gitserver's /perforce-users endpoint |
|
PerforceProtectsForUser |
list all protections that apply to a user | calls gitserver's /perforce-protects-for-user endpoint |
|
PerforceProtectsForDepot |
list all protections that apply to a depot | calls gitserver's /perforce-protects-for-depot endpoint |
|
PerforceGroupMembers |
list all members of a Perforce group | calls gitserver's /perforce-group-members endpoint |
|
IsPerforceSuperUser |
check if a given ticket is for a super level user | calls gitserver's /is-perforce-super-user endpoint |
|
PerforceGetChangelist |
get details about a perforce changelist | calls gitserver's /perforce-get-changelist endpoint |