git-selfies 📸

A modern, blazing-fast implementation of lolcommits written in Rust. Automatically capture webcam selfies every time you commit to git!

[!WARNING] This package is still a WIP and not well tested - espcially on Linux and Windows. If you hit an issue or bug, please file an issue

Features

• Fast: Pure Rust implementation with minimal overhead
• Easy to install: Single binary, no Ruby or Node.js required
• Cross-platform: Works on macOS, Linux, and Windows
• Lightweight: Small binary size and low memory footprint
• Simple: Easy configuration and setup
• Background execution: Doesn't slow down your commits

Installation

Homebrew (macOS & Linux)

brew tap biw/tap
brew install git-selfies

APT (Ubuntu/Debian)

# Download and install DEB package
wget https://github.com/biw/git-selfies/releases/latest/download/git-selfies_amd64.deb
sudo dpkg -i git-selfies_amd64.deb

Pre-built Binaries

Download pre-built binaries for your platform from the releases page:

• Linux (x86_64 and aarch64)
• macOS (Intel and Apple Silicon)
• Windows (x86_64)

Extract and copy to a directory in your PATH. See INSTALL.md for detailed instructions.

From Source

git clone https://github.com/biw/git-selfies.git
cd git-selfies
cargo build --release
sudo cp target/release/git-selfies /usr/local/bin/

Or install directly with cargo:

cargo install --git https://github.com/biw/git-selfies

For more installation options and troubleshooting, see INSTALL.md.

Quick Start

1. Enable for a Repository

Navigate to your git repository and run:

git-selfies enable

This installs a post-commit hook that will automatically capture a selfie after every commit.

2. Make a Commit

git add .
git commit -m "Add amazing feature"
# A selfie is automatically captured in the background!

3. View Your Selfies

# Open the selfies directory
git-selfies browse

# View the most recent selfie
git-selfies last

Your selfies are stored in ~/.git-selfies/<repo-name>/ with filenames based on the commit SHA.

Commands

git-selfies enable

Enable git-selfies for the current repository by installing a post-commit hook.

git-selfies disable

Disable git-selfies for the current repository by removing the post-commit hook.

git-selfies capture

Manually capture a selfie. Useful for testing.

Options:

• --sync: Run synchronously (default is background mode)

git-selfies config-camera

Interactively configure which camera to use. Presents a list of available cameras and lets you select one with arrow keys.

Options when saving:

• Save globally (for all repositories)
• Save locally (for current repository only)

git-selfies list-cameras

List all available cameras on your system.

git-selfies last

Show the most recent selfie for the current repository. Opens the image with your default image viewer.

git-selfies browse

Open the selfies directory for the current repository in your file manager.

Configuration

git-selfies supports two levels of configuration:

1. Global config: ~/.git-selfies/config.toml - applies to all repositories
2. Local config: .git-selfies/config.toml - applies to current repository only

Local configuration always takes precedence over global configuration.

Configuration Options

# Enable or disable selfie capture
enabled = true

# Camera index (0, 1, 2, etc.)
camera_index = 0

# Camera name (alternative to index)
camera_name = "FaceTime HD Camera"

Camera Selection

The easiest way to configure your camera is with the interactive tool:

git-selfies config-camera

This will:

1. List all available cameras
2. Let you select one with arrow keys
3. Ask if you want to save globally or locally

Environment Variables

• GIT_SELFIES_DISABLED=true - Temporarily disable selfie capture without removing the hook
• HOME - Used to determine the storage directory

How It Works

1. When you run git-selfies enable, it creates a post-commit hook at .git/hooks/post-commit
2. After each commit, the hook spawns a background process that:
   • Reads your camera configuration
   • Captures a single frame from your webcam
   • Overlays the commit message and SHA on the image
   • Saves it to ~/.git-selfies/<repo-name>/<short-sha>.jpg
3. The background process exits immediately so your commit isn't delayed

Troubleshooting

Camera Not Working

If you get a "Failed to open camera" error:

1. Check camera permissions (macOS): System Settings > Privacy & Security > Camera
2. List available cameras: git-selfies list-cameras
3. Configure a specific camera: git-selfies config-camera
4. Test capture: git-selfies capture --sync

Camera Already in Use

If your camera is already in use by another application (Zoom, OBS, etc.), git-selfies may not be able to access it. Close other applications or select a different camera.

Hook Not Running

Verify the hook is installed:

cat .git/hooks/post-commit

Verify the hook is executable (Unix):

ls -l .git/hooks/post-commit

Temporarily Disable

To temporarily disable without removing the hook:

export GIT_SELFIES_DISABLED=true
git commit -m "This commit won't capture a selfie"

Storage

Selfies are stored in:

~/.git-selfies/
├── my-awesome-project/
│   ├── a1b2c3d.jpg
│   ├── e4f5g6h.jpg
│   └── config.toml
└── another-project/
    ├── 1234567.jpg
    └── config.toml

• Each repository gets its own directory
• Files are named with the 7-character short commit SHA
• Each repository can have its own local configuration

Technical Details

Built With

• nokhwa - Cross-platform webcam capture
• image - Image encoding/decoding
• imageproc - Image text overlay
• clap - Command-line argument parsing
• inquire - Interactive prompts

Why Rust?

The original lolcommits is written in Ruby, which requires:

• Ruby runtime installation
• ImageMagick dependency
• Slower startup time
• Larger memory footprint

git-selfies is pure Rust, which means:

• Single binary - No runtime required
• Fast startup - Milliseconds instead of hundreds of milliseconds
• Small size - ~5-15MB binary
• Low memory - Uses ~10-20MB RAM during capture
• Easy distribution - Just copy the binary

Comparison with lolcommits

Feature	git-selfies	lolcommits
Runtime	None (compiled)	Ruby
Dependencies	None	Ruby, ImageMagick
Binary size	~5-15MB	N/A (scripted)
Startup time	<10ms	~100-200ms
Installation	Single binary	gem install + deps
Cross-platform	✅ (native)	✅ (via Ruby)
Background capture	✅	✅
Configuration	TOML	YAML
Plugins	❌ (planned)	✅

Development & Testing

Building

# Debug build
cargo build

# Release build (optimized)
cargo build --release

Running Tests

# Run unit tests
cargo test

# Run manual test suite
./test-manual.sh

Manual Testing Workflow

1. Build the project: cargo build --release
2. List cameras: ./target/release/git-selfies list-cameras
3. Configure camera: ./target/release/git-selfies config-camera
4. Test capture: ./target/release/git-selfies capture --sync
5. Enable in repo: ./target/release/git-selfies enable
6. Make a commit: git commit -m "test"
7. View selfies: ./target/release/git-selfies browse

Note: First camera capture on macOS will prompt for camera permissions. Make sure to grant access in System Settings > Privacy & Security > Camera.

CI/CD

The project uses GitHub Actions for:

• CI: Runs on every push/PR to test on Linux, macOS, and Windows
• Release: Automatically builds binaries for all platforms when a version tag is pushed

To create a release:

git tag v0.2.0
git push origin v0.2.0

Roadmap

• GIF/video capture support
• Plugin system
• Upload to cloud services (Imgur, S3, etc.)
• Timelapse generation
• Web viewer for selfies
• GitHub Actions integration
• Homebrew formula
• Debian/APT packages
• Pre-built binaries for releases
• AUR package (Arch Linux)
• Snap package
• Flatpak package

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE for details.

Credits

• Inspired by lolcommits
• Built with nokhwa by l1npengtul

Fun Stats

Made with ❤️ and Rust 🦀