# 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, `..`, `.git` or 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.` when `expectedOid` no longer matches,
  `Branch "<name>" does not exist.`, `The file is unchanged.`, or the branch protection rule that
  refused it.

## Related

- [Delete a tag](delete-a-tag.md)
- `git.files.tree` · `git.commits.create`
