Adam French
507c61fe5f
- Fix staged files being silently cleared when commit uses inline files - Refactor step navigation to use direct go_to_step instead of fragile delta math - Change step numbers from i32 to u32 (reject negative values at parse time) - Add tour rm command to mark files for removal during carry-forward - Add tour reset command to clear session and remove tracked files - Consolidate duplicate recursive copy functions into shared copy_tree in utils - Validate step directories are sequential (detect corruption) - Detect binary files in diffs instead of showing garbage - Use /// doc comments on enum variants so clap generates proper help text - Remove custom Help subcommand in favor of clap's built-in --help - Add CorruptedTour error variant for integrity checks Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
tour
A CLI tool for creating and navigating code tutorials as a series of file snapshots.
Install
cargo install --path .
Quick Start
Creating a tour
# Initialize a new tour in the current directory
tour init
# Stage and commit files as steps
tour add src/main.rs Cargo.toml
tour commit -m "After running cargo init we get our template"
# Or commit with inline file arguments
tour commit src/lib.rs -m "In lib.rs we add some functions"
tour commit src/main.rs -m "We import our newly made function from lib.rs"
# Finalize the tour
tour end -m "Now your tour is complete and you can use rust modules!"
Taking a tour
tour start
# new: Cargo.toml
# new: src/main.rs
#
# Step 1/3: After running cargo init we get our template
tour next
# new: src/lib.rs
#
# Step 2/3: In lib.rs we add some functions
tour prev
# deleted: src/lib.rs
#
# Step 1/3: After running cargo init we get our template
tour next 2
# new: src/lib.rs
# modified: src/main.rs
# + use lib::my_function;
#
# Step 3/3: We import our newly made function from lib.rs
tour step 1 # jump to any step by number
Commands
Author workflow
| Command | Description |
|---|---|
tour init |
Set up a new tour in the current directory |
tour add <files...> |
Stage files for the next commit |
tour unstage <files...> |
Remove files from staging |
tour commit -m <msg> |
Commit staged files as a new step |
tour commit <files...> -m <msg> |
Stage and commit files in one step |
tour end -m <msg> |
Finalize the tour |
Reader workflow
| Command | Description |
|---|---|
tour start |
Load the first step |
tour next [n] |
Advance n steps (default 1) |
tour prev [n] |
Go back n steps (default 1) |
tour step <n> |
Jump to step n |
Other
| Command | Description |
|---|---|
tour info |
Show tour metadata |
tour status |
Show current step and staged files |
tour list |
List all steps with messages |
tour help |
Show help message |
How it works
Each step is stored as a complete file snapshot in .tour/steps/<N>/. When navigating between steps, tour replaces tracked files in your working directory and shows a diff of what changed — new files, modified files (with line-level diffs), and deleted files.
The .tour/ directory contains:
steps/— numbered directories, each holding the full file state for that step plus amessagefilesession— tracks the reader's current positioninfo— tour metadata (author, description, language, dates)staged— files staged for the next commitended— marker indicating the tour is finalized