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 |
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 |