DocsScreens
Files
Files shows a worktree's file tree and opens its files in viewers, with each file's outline, history and similar functions alongside. It only reads files; it never edits them.
The sidebar
CHANGES lists your uncommitted changes above the file tree, where files git doesn't track are dimmed. Point at a file for Copy Path and split icons such as Open in Split Right. The sidebar button in the toolbar collapses the sidebar to icons: Uncommitted changes, File tree and your shortcuts. To add a shortcut, choose Add Shortcut on a folder's right-click menu; its panel shows the tree from that folder.
Below the tree
- Refresh (⌘R) reads git state and the tree again.
- Show File Sizes adds a size column. For a folder's total, choose Calculate Size on its right-click menu.
- Show Agent Reads marks the files agents opened with their read tool in recorded sessions, with the tokens re-read after each file entered the context, an inferred value (Tokens). Reads through shell commands aren't counted.
Tabs and splits
A click opens a file in a temporary tab, named in italics, that the next click replaces; double-click the tab to keep it. A split icon opens the file in a new pane on that side, with its own tabs and side panel.
Ways to view
Some files get a switch in the file header:
- Code: the text, highlighted.
- Preview: rendered Markdown, the default for Markdown files. To draw diagrams and math in code blocks, see Code Blocks.
- Graph: JSON, or a docker-compose file's services, networks and volumes, as a graph. The default for those files.
- Browser: HTML as a browser shows it. It's off by default because the page's scripts run and can load resources from the internet.
OUTLINE
Two buttons at the right of the file header open OUTLINE and HISTORY. OUTLINE lists the file's definitions, or a document's headings and keys; click a row to jump there. In code that Code Analysis reads, functions get the columns NAME, COG, 30D and SIMILAR:
- COG: its cognitive complexity now.
- 30D: how much that changed in the last 30 days, such as ▲ 12.
- SIMILAR: ⧉ and the approximate similarity of its closest similar function. Click it to open that function.
Until analysis is ready, the panel says Analysis pending. Select a function for a card with its complexity over time, Function History and Similar Functions.
HISTORY
HISTORY opens with Neighbors, the files that change together with this one, as a Graph or a List. The list puts Hidden Coupling, files with no link found in the code, ahead of Linked files. Below are Working tree and the commits that changed the file; select one to see its diff. After you open a function's history, the File | ƒ switch shows that function's own versions.
LINE N
Click a line number in Code to open LINE N at the top of HISTORY, listing the commits that added, changed or removed that line, oldest first. With an account connected in Accounts, you also see each commit's pull request and its review threads at the line, matched by line number and so approximate.
Definitions and usages
Double-click a name in Code for a card showing its definition and the files it's used in. When the import can't be followed, definitions are candidates found by name. Click a file in the card to go there, or press Esc to close it.
When a file changes on disk
An open tab keeps the content it opened with. When the file changes on disk, the header says Changed on disk; Compare with Disk shows the difference, and Reload from Disk loads the new content.
Keyboard shortcuts
- ⌘P Go to File…: start with
@to search definitions, or#to search text. - ⌘F Find… in the open code.
- ⇧⌘F Find in Repository… searches text across the repository.
See Keyboard shortcuts for the rest.