Browse a repository
The API operations that read files, history and diffs, and commit edits from the console.
All paths are under /git/api/repositories/{repoId}. Reading the tree, the commit list and
insights needs git:GetRepository (names and metadata only); file contents, blame, single commits
with their patch, diffs and archives need git:PullRepository, a sensitive read that is recorded
in the audit log even when allowed; committing needs git:PushRepository. Where ref is optional,
it defaults to the repository's default branch.
| Operation | What | CLI |
|---|---|---|
GET …/tree?ref=&path= |
entries under a path at a ref | dcloud git files tree |
GET …/blob?ref=&path= |
one file, rendered or highlighted (path required) |
dcloud git files blob |
GET …/raw?ref=&path=&download= |
one file verbatim, with its own content type (path required) |
dcloud git files raw |
GET …/blame?ref=&path= |
which commit last changed each line of a file | dcloud git files blame |
GET …/archive?ref=&format= |
the tree at a ref (ref required) as zip (default) or tar.gz |
dcloud git files archive |
GET …/commits?ref=&path=&limit=&skip= |
history; limit 1 to 200, skip to page |
dcloud git commits list |
GET …/commits/{sha} |
one commit with its files and patch | dcloud git commits get |
GET …/compare?base=&head= |
the diff between two refs (both required) | dcloud git commits compare |
GET …/insights |
commits per week, contributors and pull request activity | dcloud git files insights |
POST …/commits |
commit file edits to a branch, as the console's editor does | dcloud git commits create |
Committing through the API
POST …/commits takes a branch, a message (up to 2,000 characters) and 1 to 50 changes,
each { "kind": "upsert", "path", "content" } (content up to 2,000,000 characters) or
{ "kind": "delete", "path" }. Send expectedOid, the branch's commit when you started, to be
refused rather than overwrite a push made in between.
It counts as a push, so branch protection applies exactly as it does to git push. It is refused
with:
- 400
Invalid path: <path>for an absolute path,..,.gitor an empty segment. - 409 with the reason while the repository is archived, a mirror or still importing, for example
This repository is archived and read-only. Unarchive it in its settings to write to it. - 409
The branch moved since you started editing.whenexpectedOidno longer matches,Branch "<name>" does not exist.,The file is unchanged., or the branch protection rule that refused it.
Related
Related
- GET /git/api/repositories/{repoId}/tree
- GET /git/api/repositories/{repoId}/blob
- GET /git/api/repositories/{repoId}/raw
- GET /git/api/repositories/{repoId}/archive
- GET /git/api/repositories/{repoId}/blame
- GET /git/api/repositories/{repoId}/insights
- GET /git/api/repositories/{repoId}/commits
- GET /git/api/repositories/{repoId}/commits/{sha}
- GET /git/api/repositories/{repoId}/compare
- POST /git/api/repositories/{repoId}/commits