git-captains-log 0.5.1

Automatically aggregate git commit messages daily into markdown logs

Captain's Log

Automatically aggregate your git commit messages daily into markdown logs, grouped by repository and project.

---

Installation

Recommended: PyPI + CLI tools

Install Captain's Log as an isolated CLI tool and let the package manage its own dependencies:

# Using pipx (recommended)
pipx install git-captains-log

# Or using uv
uv pip install git-captains-log

# Or with plain pip (uses your current Python environment)
pip install git-captains-log

Then run the setup command:

captains-log setup

This will:

• Create ~/.captains-log/ for configuration
• Create ~/.git-hooks/ for global Git hooks
• Install or update the commit-msg hook
• Configure git config --global core.hooksPath ~/.git-hooks
• Create a default ~/.captains-log/config.yml if it does not exist

After that you can use btw, wtf, wnext, and captains-log from anywhere in your shell.

See INSTALLATION.md for more detailed installation and configuration examples.

From Source (For Development)

If you're developing Captain's Log locally:

git clone [e-mail]:koradon/captains-log.git
cd captains-log

# Install in editable mode (uses pyproject.toml dependencies)
uv pip install -e .

# Configure hooks and config file
captains-log setup

Legacy helper script (install.sh)

There is also a legacy helper script:

chmod +x install.sh
./install.sh

This script focuses on wiring up the ~/.captains-log directory and global Git hooks. It no longer installs Python dependencies globally – you are expected to install the git-captains-log package (and therefore PyYAML) via pipx, uv, or pip in whatever Python environment your Git hooks will use.

Pre-commit Integration (Optional)

If you use pre-commit in your repositories and want to keep both your global Captain's Log hooks and per-repo pre-commit hooks working together, you can install global wrapper hooks via the CLI:

# After `pipx install git-captains-log` and `captains-log setup`
captains-log install-precommit-hooks

This will:

• Install global hook wrappers in ~/.git-hooks that run pre-commit first (when .pre-commit-config.yaml exists)
• Then run Captain's Log afterwards (via ~/.captains-log/commit-msg)
• Configure git config --global core.hooksPath ~/.git-hooks (or reuse the existing value if already correct)
• Work seamlessly with repos that do and do not use pre-commit

Note: With pre-commit integration, you don't need to run pre-commit install in individual repositories. The global hooks will automatically invoke pre-commit when a repo has .pre-commit-config.yaml.

Legacy helper script (install-with-precommit.sh)

For historical reasons there is also a shell helper script:

# After running install.sh
chmod +x install-with-precommit.sh
./install-with-precommit.sh

The script performs the same kind of global wrapper installation as captains-log install-precommit-hooks, but is kept mainly for backward compatibility.

Manual Installation

If you prefer to install manually (legacy / advanced setup):

1. Clone or download Captain's Log:

git clone [e-mail]:koradon/captains-log.git ~/.captains-log
cd ~/.captains-log

2. Ensure dependencies are available

# Prefer installing the packaged tool, which brings PyYAML as a dependency:
pipx install git-captains-log
# or:
uv pip install git-captains-log
# or, if you really want to use the system environment:
pip install git-captains-log

3. Configure your projects and global log repo in ~/.captains-log/config.yml

global_log_repo: /path/to/global/log-repo

projects:
  work-repos:
    root: /path/to/work/repos/work-repos

  private-tools:
    root: /path/to/private/repos/tools
    log_repo: /path/to/private-tools/log-repo

4. Setup Git hooks globally:

mkdir -p ~/.git-hooks
cp ~/.captains-log/commit-msg ~/.git-hooks/
chmod +x ~/.git-hooks/commit-msg
git config --global core.hooksPath ~/.git-hooks

5. Make the Python script executable:

chmod +x ~/.captains-log/update_log.py

Development Setup

This project uses UV for dependency management and Just for command running. To set up the development environment:

1. Install UV if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install Just if you haven't already:

# macOS
brew install just

# Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash

# Or with cargo
cargo install just

3. Install development dependencies:

just install-test

4. Run tests:

just test

5. Run tests with coverage:

just test-cov

6. Clean up generated files:

just clean

7. Run specific tests:

just test-file test_update_log.py
just test-pattern "load_config"

Usage

Automatic Git Commit Logging

After setup, every git commit you make will update a daily markdown log file inside the configured log repository/directories.

Logs are grouped by repository name under each project, with a date-based file (e.g., 2025-08-11.md).

Manual Log Entries with btw, wtf, and wnext Commands

btw Command - Log What You Did

The btw (By The Way) command allows you to add manual entries to your daily logs from anywhere on your system:

btw "Reviewed the new API documentation"
btw "Had a productive meeting about the architecture"
btw "Fixed a bug that wasn't committed yet"

wtf Command - Log Issues and Problems

The wtf (What The Fault) command allows you to log issues, bugs, and weird behavior in the "What Broke or Got Weird" section:

wtf "API endpoint started returning 500 errors"
wtf "Database connection timeout after 10 minutes"
wtf "Tests failing intermittently on CI"

wnext Command - Log What’s Next

The wnext command lets you quickly add items to the "Whats next" section of your daily logs:

# Default: log under the current project subsection
wnext "Plan sprint backlog refinement"

# Log under a specific project subsection
wnext --project my-project "Prepare release checklist"

# Log under the generic 'other' subsection
wnext --other "Remember to update the team wiki"

How They Work:

• Smart Project Detection: Uses the same project detection logic as git commits
  • If you're in a configured project directory → logs to that project
  • If not configured → uses the current directory name as project
• Different Sections:
  • btw entries appear in the "What I did" section under "## other"
  • wtf entries appear in the "What Broke or Got Weird" section
  • wnext entries appear in the "Whats next" section, grouped by project subsection or under "## other"
• Same Infrastructure: Uses your existing Captain's Log configuration and repositories

Examples:

# From within your configured project directory
cd ~/work/my-project
btw "Completed code review for new feature"
# → Adds to my-project's daily log under "What I did" → "## other"

wtf "Found memory leak in background worker"
# → Adds to my-project's daily log under "What Broke or Got Weird" → "## other"

# From any directory
cd ~/Downloads
btw "Downloaded and reviewed the client requirements"
# → Adds to Downloads project log under "What I did"

Installation:

All three commands are automatically installed with the main Captain's Log installation:

• Accessible globally from any directory (via the pipx/pip console scripts)
• When using the legacy install.sh, wrapper scripts are installed to ~/.local/bin/btw, ~/.local/bin/wtf, and ~/.local/bin/wnext (ensure ~/.local/bin is in your PATH)

Log Format:

Your daily logs will show git commits by repository in "What I did", followed by "Whats next" (with optional subsections) and a flat list in "What Broke or Got Weird":

# What I did

## repository-name
- (abc1234) Actual git commit message

## other-repo
- (def5678) Another git commit

## other
- Manual entry added with btw command
- Another manual note

# Whats next

## my-project
- Next action logged with wnext

## other
- General next step logged with wnext --other

# What Broke or Got Weird

- Issue logged with wtf command
- Another problem to investigate

Testing

To test if your installation is working correctly:

Basic Captain's Log Test

python3 test_hook.py

This will simulate a commit and show you if the log update is working properly.

Pre-commit Integration Test

If you installed pre-commit integration, test the dispatcher:

python3 test_hook_precommit.py

This will test that the hook dispatcher correctly runs pre-commit (if configured) followed by Captain's Log.

Troubleshooting

Hook not running

• Make sure you've run install.sh and it completed successfully
• Check that git config --global core.hooksPath points to ~/.git-hooks
• Verify the commit-msg file exists in ~/.git-hooks/ and is executable

Pre-commit integration issues

• Ensure you ran captains-log setup (or install.sh for legacy) before captains-log install-precommit-hooks (or install-with-precommit.sh)
• Check that both commit-msg and commit-msg-precommit exist in ~/.git-hooks/
• If pre-commit errors occur, verify you have pre-commit installed: pip install pre-commit
• The integration only runs pre-commit in repos with .pre-commit-config.yaml

Script not found errors

• Ensure update_log.py was copied to ~/.captains-log/
• Check that the script has execute permissions: chmod +x ~/.captains-log/update_log.py

Permission errors

• Make sure both the hook and script are executable
• Check that your user has write access to the log directories

Conflicting with existing pre-commit setup

If you previously used pre-commit install in repositories:

• You can safely leave existing .git/hooks/ as they won't be used (global core.hooksPath takes precedence)
• Or clean them up with pre-commit uninstall in each repo if you prefer

btw, wtf, or wnext command not found

If the btw, wtf, or wnext commands are not accessible:

• Ensure ~/.local/bin is in your PATH: echo $PATH | grep ~/.local/bin
• Add to your shell profile if missing: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
• Verify the symlinks exist (legacy script install): ls -la ~/.local/bin/btw ~/.local/bin/wtf ~/.local/bin/wnext
• Re-run the installation if needed: ./install.sh or reinstall the package with pipx install git-captains-log