Fix bugs and improve robustness across the codebase
- 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>
This commit is contained in:
135
readme.md
135
readme.md
@@ -1,72 +1,101 @@
|
||||
# Goals
|
||||
# tour
|
||||
|
||||
The purpose of this command will be to walk through code tutorials
|
||||
A CLI tool for creating and navigating code tutorials as a series of file snapshots.
|
||||
|
||||
It will be essentially the same as git, however without branches.
|
||||
## Install
|
||||
|
||||
Through a series of commits, you can walk through code changes and see what has changed (like git diff)
|
||||
|
||||
It will work as such
|
||||
|
||||
````
|
||||
```sh
|
||||
# The format of this is:
|
||||
cargo install --path .
|
||||
```
|
||||
|
||||
command args
|
||||
# ->
|
||||
# output
|
||||
# output line 2
|
||||
## Quick Start
|
||||
|
||||
# CREATING A TOUR
|
||||
tour init -m "After running *cargo init* we get our template"
|
||||
### Creating a tour
|
||||
|
||||
```sh
|
||||
# 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"
|
||||
tour end -m "Now your tour is complete and you can use rust modules!"
|
||||
|
||||
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
|
||||
|
||||
```sh
|
||||
tour start
|
||||
# ->
|
||||
# New files:
|
||||
# ./cargo.lock
|
||||
# ./cargo.toml
|
||||
# src/main.rs
|
||||
# new: Cargo.toml
|
||||
# new: src/main.rs
|
||||
#
|
||||
# Explanation
|
||||
# After running *cargo init* we get our template
|
||||
# Step 1/3: After running cargo init we get our template
|
||||
|
||||
tour next
|
||||
# ->
|
||||
# New files:
|
||||
# src/lib.rs
|
||||
# Explanation
|
||||
# In lib.rs we add some functions
|
||||
# new: src/lib.rs
|
||||
#
|
||||
# Step 2/3: In lib.rs we add some functions
|
||||
|
||||
tour prev
|
||||
# ->
|
||||
# New files:
|
||||
# ./cargo.lock
|
||||
# ./cargo.toml
|
||||
# src/main.rs
|
||||
# deleted: src/lib.rs
|
||||
#
|
||||
# Explanation
|
||||
# After running *cargo init* we get our template
|
||||
# Step 1/3: After running cargo init we get our template
|
||||
|
||||
tour next 2
|
||||
# ->
|
||||
# No new files.
|
||||
# new: src/lib.rs
|
||||
# modified: src/main.rs
|
||||
# + use lib::my_function;
|
||||
#
|
||||
# Step 3/3: We import our newly made function from lib.rs
|
||||
|
||||
# Changes:
|
||||
# src/main.rs
|
||||
|
||||
# Explanation
|
||||
# We import our newly made function from lib.rs
|
||||
|
||||
tour next
|
||||
# ->
|
||||
# Tutorial Finished
|
||||
# Explanation
|
||||
# Now your tour is complete and you can use rust modules!
|
||||
|
||||
# EXTRAS:
|
||||
tour author -> Add information about the author if there are questions
|
||||
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 a `message` file
|
||||
- `session` — tracks the reader's current position
|
||||
- `info` — tour metadata (author, description, language, dates)
|
||||
- `staged` — files staged for the next commit
|
||||
- `ended` — marker indicating the tour is finalized
|
||||
|
||||
Reference in New Issue
Block a user