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:
ComponentSourcePurpose
profileActive config profile nameIsolates sessions per profile
ppidParent process ID (os.getppid())The shell that launched the CLI
ttyTTY 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

contree session            # show current session info
contree session list       # list all sessions
contree session show       # show full history DAG

​
Branching

Create a branch to experiment without affecting the main line: 
contree session branch experiment
contree session checkout experiment
contree run apt-get install -y curl
Not happy? Switch back: 
contree session checkout main
Branches share history entries – creating a branch just creates a new pointer at the current position. Create a branch from another branch: 
contree session branch hotfix --from main
List branches (* marks the active one): 
contree session branch

​
Rollback

Move the branch pointer in the history chain. The argument distinguishes absolute jumps from relative navigation:
ArgumentMeaning
(none)Back one entry (default)
-- -NBack N entries (the -- stops argparse from parsing -N as a flag)
+NForward N entries
N (bare positive)Absolute jump to history id N
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
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: 
# 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.
You can also set CONTREE_SESSION to any string: 
export CONTREE_SESSION=tutorial
contree use tag:python:3.11-slim
Unset it to go back to the automatic key: 
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: 
# 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
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: 
export CONTREE_HOME=/tmp/contree-data
You can experiment freely with branches. Next: Working with Files.