npm package: @horihiro/git2codetour
Description: Command-line tool to generate CodeTour from git commit diffs
Author: horihiro
Latest version: 0.0.8

# git2codetour
![NPM Version](https://img.shields.io/npm/v/%40horihiro%2Fgit2codetour)
![NPM Downloads](https://img.shields.io/npm/dy/%40horihiro%2Fgit2codetour)

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

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

or

```bash
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

```bash
npx @horihiro/git2codetour abc123 def456
```

### Output to file

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

### Specify different repository

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

### Use branch names

```bash
npx @horihiro/git2codetour main develop
```

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

### Specify three or more commits

```bash
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

```bash
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:

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

## Output Format

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

```json
{
  "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