> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync & Branches

> An optional team-wide digest of what drifted around your topics.

`driftless sync` is an **optional** team-wide digest. You almost never need it, and never to start. Drift already reaches you as a freshness badge when you `driftless context get` the area you're working on. Reach for `sync` only when you want to scan everything that moved at once.

It does not inspect your local diff and it does not retrieve file-specific context. It pulls the repo memory state from Driftless Cloud and answers one question:

> What changed around this repo's topics since I last looked?

## Command

| Command | Flags    | Description                                                 | Example          |
| ------- | -------- | ----------------------------------------------------------- | ---------------- |
| `sync`  | `--json` | Show stale topics, recent PR activity, and tracked branches | `driftless sync` |

```bash theme={"theme":"github-light"}
driftless sync
```

Typical output:

```text theme={"theme":"github-light"}
▌ acme/platform
  workspace: acme  (resolved via config)
  tracking:  main, staging

⚠  2 topics drifted, the team changed code these topics cover, context may be behind:
   auth-boundaries
     src/auth/session.ts changed
     → review the change; if it changed how this works: driftless context update auth-boundaries --what "..." --how "..."
```

## What sync checks

| Signal                 | Source                                 | What to do                                                           |
| ---------------------- | -------------------------------------- | -------------------------------------------------------------------- |
| **Stale topics**       | GitHub push events on tracked branches | Review the changed code and update the topic if the behavior changed |
| **Recent PR activity** | GitHub App observations                | Read the touched topics before working in the same area              |
| **Tracked branches**   | Repo settings in Driftless Cloud       | Use `driftless branches` to see or change drift scope                |

## When to use sync

The everyday loop doesn't need `sync`. Go straight to retrieval, which carries the freshness badge inline:

```bash theme={"theme":"github-light"}
driftless context get --files "src/auth/session.ts,src/auth/token.ts"
```

Reach for `sync` only when you want the whole team-wide picture at once:

```bash theme={"theme":"github-light"}
driftless sync
```

If you already have local changes and want matching topics for the diff:

```bash theme={"theme":"github-light"}
driftless context get --diff
```

## JSON output

Use `--json` when an agent or script needs structured output:

```bash theme={"theme":"github-light"}
driftless sync --json
```

The JSON output includes:

| Field          | Meaning                                          |
| -------------- | ------------------------------------------------ |
| `repo`         | GitHub org/repo resolved from the current remote |
| `workspace`    | Driftless workspace slug                         |
| `tracking`     | Default branch and extra tracked branches        |
| `stale_topics` | Topics whose anchored code changed               |
| `pr_activity`  | Recent PR observations and touched topics        |

## Branches

Staleness is scoped to tracked branches. If a push happens on an untracked branch, Driftless records the activity but does not mark topics stale from that branch.

| Command        | Flags      | Description           | Example                          |
| -------------- | ---------- | --------------------- | -------------------------------- |
| `branches`     | `--json`   | View tracked branches | `driftless branches`             |
| `branches add` | `<branch>` | Track a branch        | `driftless branches add staging` |
| `branches rm`  | `<branch>` | Stop tracking branch  | `driftless branches rm staging`  |