git2codetour

A command-line tool that analyzes commit logs recorded in a target Git local repository and outputs the differences between two specified commits in CodeTour format.

Usage

npx @horihiro/git2codetour <from-commit> <to-commit> [options]

or

npm install
npm run build
node dist/index.js <commit1> <commit2> ... <commitN> [options]

Arguments

• <commit1> <commit2> ... <commitN>: Two or more commit references (SHA, branch name, tag name, etc.) to generate a CodeTour showing the progression of changes

Options

• -r, --repo <path>: Path to git repository (default: current directory)
• -t, --title <title>: Title for the CodeTour
• -d, --description <description>: Description for the CodeTour
• -f, --filter <pattern1> <pattern2> ... <patternN>: Only include files matching glob patterns (e.g., src/**/*.ts *.md)
• -o, --output <file>: Output file path (default: stdout)
• -a, --append: Append steps to existing tour file (requires -o, --output option)
• -V, --version: Display version
• -h, --help: Display help

Examples

Output to stdout

npx @horihiro/git2codetour abc123 def456

Output to file

npx @horihiro/git2codetour abc123 def456 -o changes.tour

Specify different repository

npx @horihiro/git2codetour abc123 def456 -r /path/to/repo

Use branch names

npx @horihiro/git2codetour main develop

The generated tour file can be opened with the CodeTour extension in VS Code.

Specify three or more commits

npx @horihiro/git2codetour abc123 def456 ghi789 -o progression.tour

This generates a CodeTour showing the progression of changes from commit to commit (abc123 → def456, then def456 → ghi789).

Append steps to existing tour file

npx @horihiro/git2codetour abc123 def456 -o changes.tour
npx @horihiro/git2codetour def456 ghi789 -a -o changes.tour

This appends the steps from def456 to ghi789 to the existing changes.tour file and the output is same as:

npx @horihiro/git2codetour abc123 def456 ghi789 -o changes.tour

Output Format

The output is in CodeTour JSON format. Each step contains the following information:

{
  "title": "Changes from abc123 to def456",
  "description": "Diff between commits...",
  "steps": [
    {
      "file": "path/to/file.js",
      "line": 42,
      "description": "**Added:**\n```javascript\ncode here\n```"
    }
  ]
}

Supported Languages

Code blocks automatically detect the language from file extensions and apply appropriate syntax highlighting:

• JavaScript/TypeScript (.js, .jsx, .ts, .tsx)
• Python (.py)
• Java (.java)
• C/C++ (.c, .cpp, .cc, .cxx)
• C# (.cs)
• Go (.go)
• Rust (.rs)
• Ruby (.rb)
• PHP (.php)
• Shell scripts (.sh, .bash)
• HTML/CSS (.html, .css)
• JSON/YAML (.json, .yaml)
• Markdown (.md)
• Bicep (.bicep)
• And many more...

About CodeTour

CodeTour is a Visual Studio Code extension that allows you to record and play back guided walkthroughs of your codebases. The tour files generated by this tool can be used with the CodeTour extension in VS Code.

https://github.com/microsoft/codetour

License

MIT