Skip to main content
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: 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

​
Branching

Create a branch to experiment without affecting the main line:
Not happy? Switch back:
Branches share history entries – creating a branch just creates a new pointer at the current position. Create a branch from another branch:
List branches (* marks the active one):

​
Rollback

Move the branch pointer in the history chain. The argument distinguishes absolute jumps from relative navigation:
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.
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:
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.
You can also set CONTREE_SESSION to any string:
Unset it to go back to the automatic key:

​
Sharing a session across terminals

contree use prints the session key. Export it in another terminal to attach to the same session:
This pattern is CLI-only. The interactive shell manages sessions internally and does not require manual session key export.

​
Storage

Session data is stored in a per-profile SQLite database at ~/.config/contree/sessions-{profile}.db. Override the data directory with CONTREE_HOME:
You can experiment freely with branches. Next: Working with Files.