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

# Sessions, Branches & Rollback

Sessions track the current image and its history as you run commands. Every
non-disposable `contree run` produces a new image, and the session records
the chain. Sessions also support **branching** and **rollback** for
experimentation.

## Session key

Every session is identified by a **session key** – an arbitrary string.
The CLI computes one automatically so that each terminal window gets its
own session without any extra setup.

The auto-generated key is a deterministic UUID5 derived from three values:

| Component | Source                               | Purpose                         |
| --------- | ------------------------------------ | ------------------------------- |
| `profile` | Active config profile name           | Isolates sessions per profile   |
| `ppid`    | Parent process ID (`os.getppid()`)   | The shell that launched the CLI |
| `tty`     | TTY device of stdin (`os.ttyname()`) | Distinguishes terminal windows  |

**In practice this means:**

* Open a new terminal tab – new `ppid` + `tty` – **new session**.
* Run `contree` commands in the same terminal – same `ppid` + `tty` –
  **same session** (resumes where you left off).
* Switch profiles – different `profile` – **new session**.

## Viewing session state

<CodeGroup sync={false}>
  ```bash CLI theme={null}
  contree session            # show current session info
  contree session list       # list all sessions
  contree session show       # show full history DAG
  ```

  ```text Shell theme={null}
  contree session
  contree session list
  contree session show
  ```
</CodeGroup>

## Branching

Create a branch to experiment without affecting the main line:

<CodeGroup sync={false}>
  ```bash CLI theme={null}
  contree session branch experiment
  contree session checkout experiment
  contree run apt-get install -y curl
  ```

  ```text Shell theme={null}
  contree session branch experiment
  contree session checkout experiment
  apt-get install -y curl
  ```
</CodeGroup>

Not happy? Switch back:

<CodeGroup sync={false}>
  ```bash CLI theme={null}
  contree session checkout main
  ```

  ```text Shell theme={null}
  contree session checkout main
  ```
</CodeGroup>

Branches share history entries – creating a branch just creates a new
pointer at the current position.

Create a branch from another branch:

<CodeGroup sync={false}>
  ```bash CLI theme={null}
  contree session branch hotfix --from main
  ```

  ```text Shell theme={null}
  contree session branch hotfix --from main
  ```
</CodeGroup>

List branches (`*` marks the active one):

<CodeGroup sync={false}>
  ```bash CLI theme={null}
  contree session branch
  ```

  ```text Shell theme={null}
  contree session branch
  ```
</CodeGroup>

## Rollback

Move the branch pointer in the history chain. The argument distinguishes
absolute jumps from relative navigation:

| Argument            | Meaning                                                              |
| ------------------- | -------------------------------------------------------------------- |
| *(none)*            | Back one entry (default)                                             |
| `-- -N`             | Back N entries (the `--` stops argparse from parsing `-N` as a flag) |
| `+N`                | Forward N entries                                                    |
| `N` (bare positive) | **Absolute** jump to history id `N`                                  |

<CodeGroup sync={false}>
  ```bash CLI theme={null}
  contree session rollback           # back one entry
  contree session rollback -- -3     # back three entries
  contree session rollback +1        # forward one entry
  contree session rollback 42        # absolute jump to history id 42
  ```

  ```text Shell theme={null}
  contree session rollback
  contree session rollback -- -3
  contree session rollback +1
  contree session rollback 42
  ```
</CodeGroup>

<Warning>
  A bare positive number is an **absolute** history id, not “back N steps”.
  Use `--` followed by a negative number for relative back-navigation.
  Inspect with `contree session show` first to avoid surprise jumps.
</Warning>

The history entries still exist and can be recovered by creating a branch at
a specific point.

## Starting a fresh session

Because the auto-generated key is deterministic, the same terminal always
resumes the same session. Use `--new` (`-N`) to start a fresh session:

<Tabs sync={false}>
  <Tab title="CLI">
    ```bash theme={null}
    # bash / zsh
    eval $(contree use -N tag:python:3.11-slim)

    # fish
    eval (contree use -N tag:python:3.11-slim)
    ```

    Without `eval`, the new session is **not active** until you export the
    printed variable into your shell. You can also copy-paste the `export`
    (or `set -gx`) line that `contree use` prints.
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    contree use -N tag:python:3.11-slim
    ```

    Inside the interactive shell, no `eval` is needed – the new session is
    activated automatically.
  </Tab>
</Tabs>

You can also set `CONTREE_SESSION` to any string:

```bash theme={null}
export CONTREE_SESSION=tutorial
contree use tag:python:3.11-slim
```

Unset it to go back to the automatic key:

```bash theme={null}
unset CONTREE_SESSION
```

## Sharing a session across terminals

`contree use` prints the session key. Export it in another terminal to
attach to the same session:

```bash theme={null}
# Terminal 1
contree use tag:ubuntu:latest
# output: export CONTREE_SESSION=<key>

# Terminal 2 -- paste the line above
export CONTREE_SESSION=<key>
contree run ls /     # operates on the same session
```

<Note>
  This pattern is CLI-only. The interactive shell manages sessions internally
  and does not require manual session key export.
</Note>

## Storage

Session data is stored in a per-profile SQLite database at
`~/.config/contree/sessions-{profile}.db`. Override the data
directory with `CONTREE_HOME`:

```bash theme={null}
export CONTREE_HOME=/tmp/contree-data
```

***

You can experiment freely with branches. Next: [Working with Files](./files).