# Code review

Ask for a review, comment on lines of a diff, approve or request changes, and settle threads from the web app or the CLI.

## Review a pull request

Read the diff, leave a comment on a line, then give a verdict.

```sh
sailfork pr diff 12
sailfork pr review 12 --request-changes \
  --body "The migration drops a column that is still read." \
  --inline "src/db.rs:41:This drops the column."
sailfork pr review 12 --approve
```

Line comments are posted first, then the verdict. A verdict is one of two choices: approve, or request changes. A comment on its own is not a verdict.

## Ask for a review

A pull request has one reviewer. The author, or anyone with push access, sets it:

- In the web app, open the merge panel, find **Reviewer** and choose **Ask someone**, then pick a person. Anyone who can read the repository qualifies.
- From the CLI, use `sailfork pr create --reviewer ada` when you open it, or `sailfork pr edit 12 --reviewer ada` later.

The pull request then appears in the reviewer's `sailfork status` under "Waiting for your review". See [Notifications and activity](https://sailfork.com/docs/notifications). A draft asks nobody until it is marked ready.

## Review in the web app

The **Changes** section of the pull request page is the diff. Switch between **Unified** and **Split**, and tick **Viewed** on a file to mark it done.

- **Comment on a line**: choose its line number. **Shift-click another line number to comment on a range.** Click a number on the old side to comment on a line that was removed.
- **Comment on words**: select text in the diff and choose **Comment on this**. The thread is anchored to the selected characters, which stay highlighted in the diff and quoted on the thread. A selection across lines anchors to the range of lines. See [the API](https://sailfork.com/docs/api-pulls#comment-on-a-pull-request) for the fields.
- **Use the line menu**: right-click a line or a selection, or press Shift+F10 on a focused line number. The menu offers **Comment on line N** (**Comment on the selection** for words), **Suggest a change** on a line of the new side, **Copy the line** (or **Copy the selection**), **Copy a link to this line**, **Copy the file path**, **View the file at line N** and **Mark the file viewed**. Links and text fields keep the browser's menu.
- **Start a thread**: write the comment and send it. Later comments on the same line join the thread. Use **Reply** under a thread to answer it.
- **Edit or delete**: you can edit and delete your own comment, and anyone with push access can delete or fold away any comment. A folded comment shows **Show it**, and **Show it again** hides it once more.
- **Give a verdict**: in the merge panel, write in **Your review** ("What you checked, or what to change"), then choose **Approve** or **Ask for changes**. **Ask for changes** needs text. After you approve, the button reads **Approved**.

### Send comments together

Choose **Start a review** next to **Comment** to save a comment as pending instead of posting it. While a review is open, each new comment and reply reads **Add to review**, with **Comment now** and **Reply now** to post one at once. The merge panel shows "Your review has N pending comments".

Pending comments are saved on every device you use and nobody else sees them. **Send N comments** posts them all. **Approve** or **Ask for changes** sends them together with your verdict. **Discard** drops them all. Starting a review needs a signed-in account. From a script, `POST .../reviews` takes the line comments and the head commit you reviewed in one call and lands all of them or none: see [Submit a review](https://sailfork.com/docs/api-pulls#submit-a-review).

### See who is on the pull request

Faces under the pull request's title show who else has it open. Hover them to see what each person is doing, such as reading a file or writing a comment. The file list and each file header show who is on that file, and a line someone is commenting on is marked in the diff with their face. Your own other tabs are left out. An integration or agent shows under its client name, announced through `PUT .../presence`: see [Presence](https://sailfork.com/docs/api-pulls#presence). Presence is never stored.

A review's text appears in the **Conversation** section as its own entry, not attached to a file.

On your own pull request the box reads **Your self-review**. When an agent opened the pull request under your account, this is where you read what it wrote before anyone else does. Your verdict shows as "self-reviewed and approved" or "self-reviewed and asked for changes". It never counts toward the approvals from people the merge rules ask for. It meets the **Author self-review** rule when the repository has one, and a self-review that asks for changes holds the merge until you approve. Someone without write access can still comment, unless the conversation is locked.

## Rendered diffs and files

A diff draws a file as what it is where it can, and a file's header names what its lines cannot show. The pull request, commit and compare pages share these views, and the file view draws the same kinds of file.

| File | In a diff | In the file view |
| --- | --- | --- |
| Image (PNG, APNG, JPEG, GIF, WebP, AVIF, BMP, ICO) | **2-up** shows Before and After side by side with their pixel and file sizes. **Swipe** drags a divider across the two. **Onion skin** fades the new one over the old with a slider. An added or deleted image shows on its own as **Added** or **Deleted**. | The picture, with its size. |
| SVG | **Rendered** (the picture, compared like an image) or **Source** (the lines). | **Image** or **Code**. |
| CSV, TSV | **Table** or **Lines**. | **Table** or **Code**, with the row and column counts. |
| Jupyter notebook (`.ipynb`) | **Cells** or **Lines**. Cells are compared one by one: markdown rendered with the changed words marked, code as a diff, outputs before and after. | **Notebook** or **Code**. Markdown is rendered, code colored and outputs shown. |
| JSON, YAML, TOML | **Keys** or **Lines**. The changes are listed by key path, ignoring key order and formatting. A file that does not parse shows its lines with the reason. | Code. |
| Markdown, MDX | **Rendered** or **Source**, compared section by section with the changed words marked. MDX components show as cards with their props. | **Preview** or **Code**. |
| `package.json`, `Cargo.toml`, `pyproject.toml`, requirements files and lockfiles such as `go.mod`, `Gemfile.lock` and `Podfile.lock` | The packages added and the versions that moved, not the changed lines. | Code. |

Pick a view in the file's header. Choosing **Lines**, **Source** or **Code** shows the plain text. In the file view, a link to a line, such as `#L12`, opens the source.

### Files that need a careful look

A badge in the file header marks files a reviewer should read with care. The merge checklist lists them too, and only a migration still waits for a person.

| Badge | Files |
| --- | --- |
| Secrets | `.env` files other than `.env.example`, `.sample`, `.template` and `.dist`; `.pem`, `.key`, `.p12` and `.pfx` files; SSH private keys; `credentials.json` |
| CI workflow | `.github/workflows/*.yml`, `.gitlab-ci.yml`, `.circleci/config.yml` |
| Container | Dockerfiles, Containerfiles and Compose files |
| Code owners | `CODEOWNERS`, `OWNERS` |
| Migration | Anything under a `migration` or `migrations` folder |
| Infrastructure | Terraform and HCL files, and YAML under `k8s`, `kubernetes`, `helm`, `charts` or `manifests`, `Chart.yaml` and `kustomization.yaml` |

### What lines cannot show

A file header also carries a label for each of these:

- Line breaks changing between LF and CRLF, a byte order mark added or removed, and a missing final newline.
- A file becoming executable or losing it, or another mode change.
- A symlink's target, and a submodule added, moved or removed.
- A file stored in Git LFS. The diff and the file view show the real file, not the pointer, so an LFS image diffs like any other image. A pointer whose file was never uploaded says so.
- UTF-16 and Windows-1252 text, shown decoded in its own charset.
- Files your `.gitattributes` marks `linguist-generated` or `linguist-vendored`, labeled **Generated** or **Vendored**.

### Folded and large files

Lockfiles, generated and vendored files, and files with more than 400 changed lines start folded, with **Show it** to open one. A binary file reads "Binary file, not shown". A file too large to diff reads "Large file changed, so its lines are not shown here", with **Open the file**. In the file view, a file over 10 MiB shows its size and a download, plus the first 256 KB of a text file. See [Repositories](https://sailfork.com/docs/repositories#open-a-repository).

### Move around the diff

- The **Changed files** tree lists every file in the diff and filters by name.
- Press `j` and `k` to go to the next and previous file, `v` to mark the file viewed and `w` to wrap long lines. The keys work when no text field has focus. **Wrap lines** is also a button on the file view, and the choice is remembered in your browser.

## Suggestions

Put a fenced block labeled `suggestion` in a comment to propose replacement lines:

````md
```suggestion
let height = tide_height(now);
```
````

`sailfork pr feedback` and `sailfork brief` report the block as the suggested change for that thread, so a person or an agent can apply it.

## Threads

A thread is the comments on one line or range. Anyone with push access can resolve it and reopen it.

- In the web app: **Resolve** and **Unresolve** under the thread.
- From the CLI:

```sh
sailfork pr threads 12 --unresolved
sailfork pr thread resolve t-1a2b -n 12
sailfork pr thread resolve --mine -n 12
sailfork pr thread resolve --all --yes -n 12
sailfork pr thread unresolve t-1a2b -n 12
```

`--mine` resolves every unresolved thread whose last comment is yours, which is what you want after pushing fixes. `--all` resolves every unresolved thread and needs `--yes` when there is no terminal. `--dry-run` says what would happen.

When the repository's merge rules ask for it, the pull request cannot merge until every thread on a line of code is resolved. Review text that is not on a line cannot be resolved and does not count.

## Review from the CLI

### Verdicts and line comments

| Flag of `sailfork pr review [N]` | What it does |
| --- | --- |
| `--approve` | Approve. |
| `--request-changes` | Ask for changes. Needs `--body`. |
| `-b, --body <TEXT>`, `--body-file <FILE>` | The review text. `--body-file -` reads stdin. |
| `--inline <PATH:LINE:TEXT>` | A comment on a line. `LINE` is `12` or a range `12-18`. Write `PATH:LINE@old:TEXT` for the old side. Repeat for several. |

Give `--inline` alone to post line comments with no verdict. If a comment fails, the command stops and says how many posted and that no verdict was recorded.

### Comments and replies

```sh
sailfork pr comment 12 --body "Rebased on main."
sailfork pr comment 12 --path src/db.rs --line 41 --body "Add an index here."
sailfork pr comment 12 --path src/db.rs --start-line 38 --line 41 --side old --body "Still read here."
sailfork pr comment 12 --reply-to t-1a2b --body "Fixed in the last commit."
```

`--path` with `--line` comments on a line of the diff, `--start-line` starts a range, `--side old|new` picks the side (default `new`), and `--reply-to <THREAD>` answers a thread by the id `pr threads` prints. `--attach <PATH>` uploads a file and links it, and images and videos show inline.

### Read the open feedback

`sailfork pr feedback 12` lists the unresolved threads by file, with the code each one points at and any suggested change. `sailfork pr threads 12` lists threads and conversation comments (`pr comments` is the same command). Both take `--json`, which is what an agent loop reads.

```sh
sailfork pr feedback 12 --json --jq '.threads[] | "\(.path):\(.line) \(.id)"'
```

`sailfork wait pr 12 --review` blocks until a new review or comment arrives and exits 1 if the review asks for changes.

## What a review changes

- **Approvals** count toward the merge rules. The rules count people other than the author, and each person's latest review is the one that counts. When the rules dismiss stale approvals, an approval from before the latest push no longer counts, and the merge panel says so.
- **Changes requested** blocks the merge until the reviewer approves. Someone with push access can also choose **Dismiss the request** in the merge panel. The review goes back to "requested" with the same reviewer. It is refused for the reviewer who asked for the changes, who should review again instead.
- **Threads** can hold the merge, as above.

The full list of what stops a merge is in [Pull requests](https://sailfork.com/docs/pull-requests#what-blocks-a-merge).

## Automated reviews and agent approvals

An agent's approval is shown, but the merge panel does not count it toward the approvals a repository asks for. A person has to approve.

A caisson can also be reviewed adversarially by an agent. The review posts as a comment, never as an approval, and each high or critical finding opens a thread on its line. When the owner's policy requires it, a pull request from a caisson is held until the code carries a review that meets the policy: `caisson/c-z4nwicj7 has not been cleared by review`. See [Caissons](https://sailfork.com/docs/caissons) and [Agents](https://sailfork.com/docs/agents).

## What "waiting on you" means

`sailfork status` has a section named "Waiting for your review". It lists the open pull requests that ask you to review them, up to 50. The other sections are "Your pull requests", with their checks and review state, and "Assigned to you", for issues. Add `-R fenil/ocean-landing` to see one repository.

```sh
sailfork status
sailfork status -R acme/site --json
```

In the web app, a repository's **Pull requests** page groups open work as **Waiting on you** and **Waiting on others**, and its inbox leads with the pull requests you did not open and have not reviewed. Choosing one shows why it needs you, its checks and size, and offers **Approve** (or **Approve and merge** when nothing holds it back) and **Request changes**.

## Who can do what

| Action | Who |
| --- | --- |
| Comment on a line, reply | Anyone who can read the repository, unless the conversation is locked or the owner blocked them. |
| Edit a comment | Its author. |
| Delete or fold a comment | Its author for deleting, and anyone with push access for either. |
| Approve, request changes | Anyone with push access. The author can too, as a self-review that never counts toward approvals. |
| Resolve, unresolve, dismiss a request | Anyone with push access. |
| Ask for a reviewer | The author, and anyone with push access. |

## From a script

The review, comment, thread and dismiss routes are in [the API reference](https://sailfork.com/docs/api). The [MCP server](https://sailfork.com/docs/mcp) has the same tools for agents.

## Errors people hit

- `--request-changes` needs `--body`.
- `pull request ... is already merged`: a verdict cannot change a merged pull request.
- A write to a locked conversation by someone without write access answers 403.

---

Every docs page: https://sailfork.com/llms.txt
