commit-celebration

A tiny, cross‑platform tool that plays a short celebration sound after every successful git commit. Install it once as a global git hook; customize the sounds to your taste; keep the rest of your workflow untouched.

Credits: The default sounds are sourced from https://www.freesoundslibrary.com/ — huge thanks to the creators and the library.

Overview

• Global post-commit hook: enabled once, works for all repos.
• Offline after first run: sounds are cached locally.
• Fully customizable: drop your own .mp3/.wav/.m4a files.
• No config files, no daemons, no shell wrappers.
• macOS, Linux, and Windows support.

Under the hood, the hook launches the commit-celebration binary in the background. The app ensures sounds exist locally, downloads the latest sounds pack from GitHub Releases if needed, picks a random file, and plays it using the platform’s native player.

How to install and use

Prerequisites:

• Git installed.
• Audio capability:
  • macOS: afplay (built-in)
  • Linux: one of paplay, aplay, or mpg123
  • Windows: PowerShell SoundPlayer

One‑line install

Run this in your terminal:

curl -fsSL https://raw.githubusercontent.com/divyanshusahu/commit-celebration/HEAD/install.sh | bash

What this does:

• Downloads the latest commit-celebration binary for your OS/arch to ~/.local/bin
• Makes it executable
• Runs commit-celebration install to enable a global post-commit hook
• Leaves a note if ~/.local/bin is not on your PATH

Enable/disable the global hook

• Enable (done automatically by the installer): commit-celebration install
• Disable and revert: commit-celebration uninstall

Now make a commit anywhere and enjoy a celebratory sound.

3) Customize the sounds

• Default non-dev location: ~/.commit-celebration/sounds
• Dev builds (running from source): ./sounds (relative to the repo root)

How to customize:

• Drop your own .mp3, .wav, or .m4a files into the sounds folder.
• Remove any files you don’t want.
• The app picks a random file each time.

Important note about the update command: commit-celebration update now updates both the binary and the sounds. If you’ve added custom files to the sounds folder, back them up first; the folder will be refreshed from the latest release.

Upgrade

• Self-update to the latest release (binary + sounds): commit-celebration update
• Verify version: commit-celebration version

Uninstall

• Disable global hook: commit-celebration uninstall
• Optional cleanup:
  • Remove the sounds cache: rm -rf ~/.commit-celebration
  • Remove the binary from your PATH (e.g., ~/.local/bin/commit-celebration)

How it is built (and how it works)

• The global post-commit hook script is written to ~/.commit-celebration/git-hooks/post-commit and runs the binary in the background.
• On execution, the app ensures a local sounds cache exists. If empty, it resolves a release tag (embedded at build-time, or via GitHub’s releases/latest), downloads sounds-pack.zip from the repository’s Releases, and extracts it into the sounds directory.
• A random track is selected and played using:
  • macOS: afplay
  • Linux: paplay, aplay, or mpg123 (first available)
  • Windows: PowerShell Media.SoundPlayer

Self‑update behavior (commit-celebration update):

• Resolves the latest GitHub release tag
• Downloads the OS/arch‑specific binary and replaces the current executable (POSIX)
• On Windows, writes a .new file alongside the current .exe (manual swap required)
• Clears and refreshes the sounds cache from the sounds-pack.zip asset

Build and release:

• Standard Go static binaries built per OS/arch (see release.sh).
• Build-time variables (Version, BuildTime) are injected via -ldflags.
• Sounds pack is zipped as sounds-pack.zip and published with the release.

Local development setup

Requirements:

• Go 1.21+ (module targets Go 1.24)
• zip utility (for releasing)
• GitHub CLI (gh) if you plan to publish releases

Quick start:

• Add a couple of small .mp3/.wav files under ./sounds.
• Build and run locally:
  • go build -o commit-celebration
  • ./commit-celebration (plays a random sound)
  • ./commit-celebration version
• Test the hook end‑to‑end:
  • ./commit-celebration install
  • Make a commit in any repo
  • ./commit-celebration uninstall to revert

Releasing (maintainers):

• Prepare sounds under ./sounds.
• Run ./release.sh vX.Y.Z.
• Artifacts are produced under ./dist/ and uploaded via gh release.

Badges and demo

Contributing guide

We welcome contributions that keep the tool simple and robust.

• Open an issue to discuss significant changes first.
• Keep pull requests small and focused.
• Follow idiomatic Go; run go fmt.
• Update this README if behavior changes.

Troubleshooting

• No sound on Linux: install one of paplay, aplay, or mpg123 and ensure it is on PATH.
• Already using a global hooks path: the tool sets git config --global core.hooksPath to ~/.commit-celebration/git-hooks. If you rely on another global hooks setup, merge your logic into the generated post-commit or avoid installing globally.
• Network restrictions: the app contacts GitHub (API + Releases) to fetch the latest version and the sounds pack. Ensure HTTPS to GitHub is allowed.

Security & privacy

• No telemetry, no background daemons.
• Network access only to GitHub when updating/version-detecting or downloading sounds.

License

MIT License. See LICENSE for details.

Audio credit: Default sounds are from https://www.freesoundslibrary.com/ and retain their respective licenses/attributions from that source.

—

Built with Go. Have fun shipping—one commit at a time.