# Changes and the code view

> Read what a worker changed on a ticket, browse and edit its code, and leave a line comment for the agent or the pull request.

This page helps you review a worker's code without leaving the ticket. By the end you'll know how to read its
changes, browse and edit the files it works on, and point the agent at the exact lines you mean.

Every ticket a worker has run on has two code views beside its feed. **Changes** shows the diff: what the worker
changed, compared the way you choose. **Code** is a file browser for the ticket's repos, at any revision. Both read
the ticket's [worktree](https://docs.bydawn.com/worktrees/) on the machine it ran on, so they work while the agent is running, between
runs and after it has finished.

## Open them

Open the ticket and pick **Changes** or **Code** in the row of views at the top, next to **Feed** and **Terminal**.
Hold `⌥` while you click a view to open it beside the one you're on. `⌘⇧K` opens Feed
and Code side by side (`⌘⌥⇧K` in a browser, which keeps the shorter chord for itself), and
`⌘\` turns the split off again.

Each view has its own address, so you can send someone a link straight to it: the ticket's address followed by
`/changes` or `/code`, such as `/p/SAW/t/SAW-1288/changes`.

On a phone, the views are grouped into rooms. Both live in the **Code** room, as **Changes** and **Files**.

When the ticket dialog opens, By Dawn connects to the ticket's machine straight away, so the diff is usually ready by
the time you pick **Changes**. The views show **Live** while that connection is up, **Connecting** while it's being
made, and **Offline** when the machine can't be reached ([below](#when-the-machine-is-away)).

## Changes

### Choose what to compare

The **Compare** switch at the top decides what the diff is against:

| Option | What it shows |
| --- | --- |
| **Uncommitted** | The files on disk against the last commit, including new files git doesn't track yet. What the agent is in the middle of. |
| **Whole branch** | Everything the ticket's branch has committed since it left the branch it opens into. What a pull request would contain. |
| **Per commit** | One commit at a time. Pick it from the branch's commits, listed above the files. |
| **Pull request** | The pull request as GitHub shows it. Only offered once the ticket has one, and covered in [Review a pull request in By Dawn](https://docs.bydawn.com/pull-requests/#review-a-pull-request-in-by-dawn). |

Changes opens on **Uncommitted** when the worker has changes it hasn't committed yet, and on **Whole branch**
otherwise. The diff updates on its own as the worker edits files, so you can watch a change take shape.

A ticket that works in several repos shows them all in one diff, grouped by repo in the file list. Each repo's
heading shows its branch, the branch it opens into and its total lines added and removed. **Per commit** and
**Pull request** show only the repo the commit or pull request belongs to.

### The file list

The list on the left has one row per changed file: a letter for what happened to it (**A** added, **M** modified,
**D** deleted, **R** renamed, **U** untracked, and so on), its path, and the lines added and removed. Repos with
nothing to show fold into one row at the end, such as "2 repos with no changes". A change over 2,000 files is
listed only in part, and the list says so.

Choose **Split the diff** or **Stack the diff** to see old and new side by side or one above the other. By Dawn
remembers the choice on this device. A pane narrower than 768 pixels always stacks, and hides the file list
behind **Show changed files**.

### Mark files viewed

Tick a file's **Viewed** box, in the list or on the file's heading, once you've read it. The file collapses to its
heading, and the counter at the top shows how far you've got, for example "4/9 viewed". If the file changes again,
the tick clears itself, so a tick always means you've seen the file as it is now.

Ticks are kept separately for each comparison, and for each pull request. They're saved on this device only, so
they don't follow you to another computer and other people don't see them.

### Move around with the keyboard

| Keys | Does |
| --- | --- |
| `J` / `K` | Next / previous file |
| `N` / `P` | Next / previous change in the diff, across files |
| `⌘P` | **Go to changed file**: type part of a path, then `Enter` |

The single-letter keys don't fire while you're typing in a box. A reminder of them sits at the foot of the file
list.

## Comment on a line

A **line comment** points the agent, or the pull request, at the exact lines you mean, so you don't have to
describe where the problem is. You can leave one in any comparison in **Changes**.

1. Click the **+** that appears beside a line, or click a line number. Drag over several lines to pick a range.
2. Type your comment in the card that opens under the lines. Its heading shows what you picked, such as
   `src/billing/invoice.ts:12-18`.
3. Choose where it goes:
   - **Send to agent**: the ticket's running worker gets it straight away, like a message from the composer.
   - **Post to #N**, in **Pull request** mode only: By Dawn posts it on the pull request on GitHub, on those lines.
   - **Both**, in **Pull request** mode only: both of the above.

*[Screenshot: Changes in Uncommitted mode: the file list of two repos on the left, and a line comment card open under lines 4 to 6 of a file, with Cancel and Send to agent]*

`⌘+Enter` sends it to the agent, or to both in **Pull request** mode, and `Esc` cancels
it. Picking other lines moves the card there and keeps what you've typed.

**What the agent gets.** The comment names the lines and the comparison you were looking at, and the agent's
machine quotes those lines from the ticket's own worktree before the agent reads it. So the agent sees your words
next to the code you meant, and the code itself never passes through By Dawn's servers.

**What the pull request gets.** A review comment on GitHub, on the commit the diff was drawn from, signed "Posted
from SAW by" you. A later push marks it outdated on GitHub rather than losing it. It then shows in the diff as a
[review thread](https://docs.bydawn.com/pull-requests/#review-threads).

Once it's sent, the card becomes a note under the lines with a line for each place it went, such as "Sent to the
agent." or "Posted on #42.", and a **Dismiss** button. If one of them fails, the card stays open with the reason and
sends only to what failed when you try again. The notes are a record for you while you review: they're gone when
you switch comparison or close the ticket, and the comments themselves live with the agent and on GitHub.

| What the card says | What to do |
| --- | --- |
| "No agent is running on this ticket — start one, then send it again." | Start the ticket, then send it again. |
| "The agent didn't take it — it may have just finished. Try again." | The worker finished its turn as you sent it. Send it again. |
| "GitHub can only take a comment on lines inside the pull request's diff — these aren't." | Pick lines the pull request changes, or send it to the agent only. |
| "Line comments aren't available on Azure DevOps pull requests yet." | Send it to the agent instead. |

## Code

**Code** is a file browser for the ticket's repos. Pick a repo in **Repository** when the ticket has more than one,
and a revision in **Revision**:

- **Worktree (on disk)**: the files as they are on the machine right now, including what the agent hasn't
  committed. This is where Code opens.
- **HEAD**, the ticket's branch, or the branch it opens into, marked **(branch)** and **(target)**.
- one of the **Recent commits**, the 20 newest.
- **Other ref…**: type a branch, tag or commit SHA and choose **Go**.

Each repo keeps its own revision and open file, so switching repos doesn't lose your place.

Open folders in the tree on the left, or press `⌘P` (**Find file**) and type part of a file's
name. Large repos are indexed as you type, and folders such as `node_modules` may be skipped. The tree works
from the keyboard too: the arrow keys move and open folders, and `Enter` opens a file. A file opens
with its path above it: click a folder in the path to show it in the tree, or copy the path. Binary files show
only their size, and a file over 1 MiB shows its first 1 MiB.

### Edit a file

You can fix a file yourself instead of asking the agent. Open it at **Worktree (on disk)** and choose **Edit**.
Save with **Save** or `⌘S`, and choose **Done** when you've finished. The file is written into the
ticket's worktree on the machine, so the agent sees your change on its next look, and it shows in **Changes** as
uncommitted.

Only text files of up to 1 MiB, opened at the worktree, can be edited. When **Edit** is greyed out, hover over it to
see why.

The agent may be editing the same files, so By Dawn never overwrites a change you haven't seen:

- If the file changed on disk after you opened it, a banner says so, and saving asks first in **This file changed
  on disk**: **Reload — discard my edits** or **Overwrite with mine**.
- If the agent is in the middle of a turn, **The agent is working** asks whether to **Wait** or **Save anyway**.
  Waiting keeps your edits in the editor.
- Leaving a file with unsaved edits asks **Discard unsaved changes?** first.

## When the machine is away

Both views read the ticket's code from its machine, so they need the machine to be reachable. When it isn't, they
say why, offer **Retry** where trying again can help, and show the worker's last finish summary instead:

- "The ticket's machine is offline." The machine is off or has lost its connection.
- "This ticket has not run on a machine yet, so there is no code to show." Start the ticket first.
- "You don't have access to this ticket's code."
- "This ticket's code was cleared from its machine — reclaimed work is kept for 30 days."

Once a worktree has been reclaimed (see [Worktrees](https://docs.bydawn.com/worktrees/)), there's nothing left on disk to compare:
**Uncommitted** and **Whole branch** are greyed out, and Changes opens on the pull request or one commit
instead. Code can still show the pull request's head and base.

## FAQ

**Can other people see which files I've marked viewed?**

No. Ticks are saved in this browser or app only, for you. Another reviewer keeps their own.

**Why can't I comment on a line in Code?**

Line comments live in **Changes**, because a comment is about a change. To point at an unchanged line, find it in
**Whole branch** if the branch touches that file, or describe it in a message to the agent.

**Does a line comment wait for me to finish a review, as on GitHub?**

No. Each comment goes out as soon as you send it, so the agent can act on it while you carry on reading.

**Is there a setting to hide whitespace changes?**

Not yet. The diff shows every change, whitespace included.

## Next

- [Pull requests](https://docs.bydawn.com/pull-requests/): follow a ticket's pull requests, review one in By Dawn and merge it.
- [Worktrees](https://docs.bydawn.com/worktrees/): where the code these views read lives, and when By Dawn clears it.

Source: https://docs.bydawn.com/changes-and-code-view/