Git Log - Commit & Documentation

Generate structured commit messages and maintain comprehensive git log documentation for the VRP toolkit project.

When to Use

Use this skill when:

• Preparing to commit changes to the repository

• Reviewing git history to understand recent changes

• Maintaining the project's change documentation

• Need quick reference for common git commands

• Want to ensure consistent commit message formatting

Core Workflow: Commit & Log

Step 1: Analyze Changes

Before committing, analyze the current changes:

git status git diff --staged # If changes already staged git diff # If changes not staged

Key questions to answer:

• What files were modified/added/deleted?

• What is the nature of changes (feature, bug fix, docs, refactor)?

• What scope is affected (e.g., architecture, setup, migration)?

Step 2: Generate Commit Message

Based on the changes, generate a commit message following Conventional Commits format:

Format: <type>(<scope>): <subject>

Common types for this project:

• feat : New feature or functionality

• fix : Bug fix

• docs : Documentation changes

• refactor : Code refactoring (no behavior change)

• test : Adding or updating tests

• chore : Maintenance tasks, dependency updates

• style : Code style changes (formatting, etc.)

Common scopes for this project:

• architecture : Changes to overall architecture

• migration : File migrations from SDR_stochastic

• setup : Project setup, installation, dependencies

• alns : ALNS algorithm changes

• pdptw : PDPTW problem definition

• data : Data layer changes

• visualization : Visualization tools

• tutorials : Tutorial notebooks

Subject guidelines:

• Use imperative mood: "add" not "added" or "adds"

• First letter lowercase

• No period at end

• Keep under 50 characters if possible

Body (optional but recommended):

• Explain what changed and why

• Use bullet points for multiple changes

• Reference issues or related work

Examples:

feat(architecture): implement unified Solver interface for problem-algorithm separation

• Create VRPProblem, VRPSolution, Solver abstract base classes
• Implement ALNSSolver adapter pattern
• Update quickstart tutorial to demonstrate new interface

chore: update migration progress (9/9 files)

• Update CLAUDE.md completed tasks section
• Add migration entry to MIGRATION_LOG.md
• Update progress statistics

Step 3: Maintain Git Log Documentation

After committing, update the git log documentation file (.claude/GIT_LOG.md ):

File structure:

Git Log - VRP Toolkit Project

Comprehensive record of all commits with detailed information.

Recent Commits (newest first)

2026-01-01 - feat(architecture): implement unified Solver interface

Hash: 4569fa1 Author: [Author Name] Date: 2026-01-01 12:34:56

Changes:

• Created base.py module with abstract base classes
• Implemented adapter pattern for backward compatibility
• Updated quickstart tutorial

Files modified:

• vrp_toolkit/algorithms/base.py
• vrp_toolkit/algorithms/alns/solver.py
• tutorials/01_quickstart.ipynb

2025-12-31 - chore: update migration progress (9/9)

Hash: 9590014 Author: [Author Name] Date: 2025-12-31 10:20:30

Changes:

• Updated CLAUDE.md with completed migration status
• Added final migration entry to MIGRATION_LOG.md

Files modified:

• .claude/CLAUDE.md
• .claude/MIGRATION_LOG.md

Update process:

• Extract commit information: git log -1 --pretty=format:"%H|%an|%ad|%s" --date=iso

• Get changed files: git show --name-only --pretty=format:"" HEAD

• Format entry using template above

• Add to top of "Recent Commits" section in .claude/GIT_LOG.md

• Keep only last 20-30 commits in main section (archive older ones if needed)

Step 4: Execute Commit

Provide the user with exact commands to execute:

Stage changes

git add [file1] [file2] ...

Commit with generated message

git commit -m "feat(architecture): implement unified Solver interface

• Create VRPProblem, VRPSolution, Solver abstract base classes
• Implement ALNSSolver adapter pattern
• Update quickstart tutorial to demonstrate new interface"

Push to remote (if desired)

git push

Quick Command Reference

Status & Diff

git status -s # Short status git diff # Unstaged changes git diff --staged # Staged changes git diff HEAD~1 # Compare with previous commit

Commit Operations

git commit -am "msg" # Stage tracked files and commit git commit --amend # Amend last commit git commit --amend --no-edit # Amend without changing message

Branch Operations

git checkout -b feature-name # Create and switch branch git switch -c feature-name # Modern equivalent git branch -d branch-name # Delete local branch

History & Log

git log --oneline -10 # Last 10 commits, one line git log --oneline --graph --all # Graphical history git show HEAD # Show last commit details

Undo & Reset

git restore --staged file.py # Unstage file git restore file.py # Discard unstaged changes git reset --soft HEAD~1 # Undo commit, keep changes

Integration with Other Skills

update-progress: After updating CLAUDE.md and MIGRATION_LOG.md, use git-workflow to commit the documentation updates.

migrate-module: After migrating files, use git-workflow to commit the migrated code.

build-session-context: Read GIT_LOG.md to understand recent changes when starting a session.

update-task-board: Use GIT_LOG.md to track completion of development tasks.

Project-Specific Patterns

Migration Commits

git add vrp_toolkit/problems/pdptw.py git commit -m "feat(migration): migrate instance.py to pdptw.py

• Extract generic Instance class
• Add type hints and docstrings
• Create basic test suite"

Progress Update Commits

git add .claude/CLAUDE.md .claude/MIGRATION_LOG.md git commit -m "chore: update migration progress (5/9 files)

• Mark instance.py migration as completed
• Update progress statistics
• Add detailed migration entry"

Tutorial/Example Commits

git add tutorials/01_quickstart.ipynb git commit -m "docs: add quickstart tutorial

• Show basic instance creation
• Demonstrate ALNS solving
• Include visualization examples"

GIT_LOG.md Maintenance

Initial Setup

If .claude/GIT_LOG.md doesn't exist, create it with the structure above.

Regular Updates

After each commit, update GIT_LOG.md with the new commit information.

Archive Strategy

• Keep last 20 commits in "Recent Commits" section

• Move older commits to "Archive" section at bottom

• Consider monthly archives if volume is high

Automation Notes

When AI uses this skill, it should:

• Analyze current git changes

• Generate appropriate commit message

• Show user exact commands to execute

• After commit, update GIT_LOG.md with new entry

• Keep GIT_LOG.md organized and readable

Troubleshooting

Empty Commit Message

If commit message seems generic, ask:

• What specific functionality was added/fixed?

• Which files were most significantly changed?

• What problem does this change solve?

Multiple Change Types

If changes include mixed types (e.g., feat and fix):

• Create separate commits if possible

• If must combine, use most significant type and explain in body

Missing GIT_LOG.md

If file doesn't exist, create it with current commit history:

Get last 20 commits for initial log

git log --oneline -20