push-it-real-good

A git hook that plays Salt-N-Pepa's "Push It" when you push.

Features graffiti-style ASCII art of "PUSH IT REAL GOOD" with a rainbow spray effect, plus video/audio playback from the classic music video.

About

This project was created as a tribute to the classic Salt-N-Pepa song "Push It" and was written for my friend Sidney Cox (@rsc3) after a conversation about git push commands.

The hook plays random clips from the official "Push It" music video featuring the iconic 80s choreography and the unforgettable "push it real good!" lyrics.

Preview

The animation displays the text "PUSH IT REAL GOOD" in bold graffiti-style letters with a spray effect from the center, rendered in a rainbow gradient (red → orange → yellow → green → blue → indigo → violet).

Features

• Rainbow ASCII art with figlet + lolcat (or pure bash fallback)
• Video playback support - Uses mpv to play random videos from media/ directory
  • Large centered window (50% of screen size)
  • Auto-closes when video completes
  • Falls back to audio if mpv not available
• Random MP3 audio playback from media/ directory
• Multimodal experience - ASCII art displays alongside video/audio
• Different media (video or audio) plays on each push for variety
• Cross-platform support (macOS, Windows, Linux)
• Zero Python dependencies - Uses native tools only
• Runs on every git push (not just force pushes)

Installation

Installation Scope

Important: This git hook is installed per-repository only. It will only trigger for git push operations in the repository where you run the installation script.

The hook is installed to .git/hooks/pre-push in the current repository and does not support global installation across all repositories. If you want to use this hook in multiple repositories, you need to install it separately in each one.

For advanced users: Global installation would require setting up git hook templates using git config --global init.templateDir, but this is not recommended for this hook since it expects media files in specific repository locations.

Prerequisites

None required! The hook works with pure bash and has smart fallbacks.

Optional (for best experience):

• figlet - Creates ASCII art text
• lolcat - Adds rainbow gradient colors
• mpv - Plays video clips
• yt-dlp - Downloads videos for media installation
• ffmpeg - Processes video clips for media installation

Quick Install

1. Clone this repository

2. (Optional) Install dependencies for enhanced experience:

   macOS:

   # For display enhancement
   brew install figlet lolcat mpv
   
   # For media file installation (if using install-media.sh)
   brew install yt-dlp ffmpeg

   Linux (Debian/Ubuntu):

   # For display enhancement
   sudo apt-get install figlet lolcat mpv
   
   # For media file installation (if using install-media.sh)
   sudo apt-get install yt-dlp ffmpeg

   Linux (Fedora):

   # For display enhancement
   sudo dnf install figlet lolcat mpv
   
   # For media file installation (if using install-media.sh)
   sudo dnf install yt-dlp ffmpeg

   Windows:

   # Using Scoop
   scoop install figlet lolcat mpv yt-dlp ffmpeg

   Or download mpv from: https://mpv.io/installation/

3. Run the installation script:

   macOS/Linux:

   ./install.sh

   Windows:

   install.bat

The installer will:

• Check for optional dependencies (figlet, lolcat, mpv)
• Offer to install them if you want (optional)
• Install the git hook
• The hook works immediately, even without optional dependencies

4. (Optional) Add media files:

   Option A: Auto-download Salt-N-Pepa 'Push It' clips

   ./install-media.sh

   This will automatically:

   • Download the official Salt-N-Pepa "Push It" music video
   • Extract 6 different clips at the best moments
   • Set up both video and audio files
   • Requires: yt-dlp and ffmpeg (install these first in step 2)

   Option B: Add your own media files

   • For video: Place video files (.webm, .mp4, .mkv, .avi, .mov) in the media/ directory
   • For audio: Place MP3 files in the media/ directory
   • The hook will randomly select one to play on each push
   • Video takes priority if mpv is installed (falls back to audio otherwise)
   • Alternatively, place a single file named push-it-real-good.mp3 in the repository root

   Note: Files starting with source- (e.g., source-video.mp4) are ignored by the hook. This is useful for keeping original/full-length files that you trim clips from.

Usage

Once installed, the hook automatically runs on every git push. You'll see:

1. Rainbow ASCII art "PUSH IT REAL GOOD" in your terminal
2. A random video clip in a large centered window (50% of screen) if mpv is installed
   • OR a random MP3 audio clip if mpv is not available
3. Your push continues normally

The ASCII art and video/audio play simultaneously for a multimodal experience!

The video/audio plays in the background and automatically closes when finished.

You can also test the hook manually:

./test.sh

To preview the full hook experience (ASCII art + random video/audio) without pushing:

./test.sh

Testing

To preview what will happen on every git push:

./test.sh

This will:

• Show which media files are available
• Display the ASCII art with rainbow colors (if figlet/lolcat installed)
• Play a random video or audio clip
• Verify the hook is properly installed

Manual Installation

If you prefer to install manually:

1. (Optional) Install dependencies for best experience:

   # macOS
   brew install figlet lolcat mpv
   
   # For media installation (if using install-media.sh)
   brew install yt-dlp ffmpeg
   
   # Linux (Debian/Ubuntu)
   sudo apt-get install figlet lolcat mpv
   sudo apt-get install yt-dlp ffmpeg
   
   # Linux (Fedora)
   sudo dnf install figlet lolcat mpv
   sudo dnf install yt-dlp ffmpeg

2. Copy the hook to your git hooks directory:

   cp pre-push .git/hooks/pre-push
   chmod +x .git/hooks/pre-push

That's it! No Python, no venv, no pip. Just bash and optional native tools.

Dependencies

Required

• Bash - For the hook script (you already have this!)
• Git - For git hooks (you already have this!)

Optional (For Enhanced Experience)

• figlet - ASCII art text generator
  • macOS: brew install figlet
  • Linux: apt install figlet or dnf install figlet
  • Windows: scoop install figlet
• lolcat - Rainbow gradient colorizer
  • macOS: brew install lolcat
  • Linux: apt install lolcat or dnf install lolcat
  • Ruby gem: gem install lolcat
  • Windows: scoop install lolcat
• mpv - Modern media player for video playback
  • macOS: brew install mpv
  • Linux: apt install mpv or dnf install mpv
  • Windows: Download from https://mpv.io/installation/

Optional (For Media Installation)

• yt-dlp - Video downloader (required for install-media.sh)
  • macOS: brew install yt-dlp
  • Linux: apt install yt-dlp or dnf install yt-dlp
  • Windows: scoop install yt-dlp
• ffmpeg - Video processing tool (required for install-media.sh)
  • macOS: brew install ffmpeg
  • Linux: apt install ffmpeg or dnf install ffmpeg
  • Windows: scoop install ffmpeg

Fallback Behavior

• No figlet/lolcat: Uses hardcoded colorful ASCII art
• No mpv: Falls back to audio playback only
• No audio player: Shows ASCII art only

The hook works with ZERO external dependencies - everything else just makes it better.

Customization

Creating Custom Media Clips

Want to create your own video or audio clips from the source material (or any other media file)? Use the trim scripts in the scripts/ directory!

For Video Clips:

./scripts/trim-video <input_file> <start_time> <end_time> [output_name]

For Audio Clips:

./scripts/trim-mp3 <input_file> <start_time> <end_time> [output_name]

Examples:

# Create a clip from 1:49 to 1:56 with auto-generated name
./scripts/trim-video media/source-video.webm 01:49 01:56

# Create a clip with a custom name
./scripts/trim-video media/source-video.webm 01:49 01:56 my-favorite-moment

# Trim an audio file
./scripts/trim-mp3 media/push-it-real-good.mp3 02:26 02:28 short-clip

Time Format:

• Use mm:ss format (e.g., 01:49) for timestamps under 1 hour
• Use hh:mm:ss format (e.g., 01:30:45) for longer media

Tips:

• The output file is created in the same directory as the input file
• If you don't specify an output name, it will be auto-generated based on the timestamps
• Custom output names should NOT include the file extension
• The clips are created with the same format/extension as the source file
• Requires ffmpeg to be installed

Customizing the ASCII Art

Want to customize the ASCII art?

1. Change the font: Edit pre-push and modify the figlet -f flag:

   figlet -f banner "YOUR TEXT"
   # Try: banner, big, standard, script, etc.

2. Change the text: Edit the text variable in the show_animation() function

3. Adjust lolcat colors: Modify the -F flag (frequency):

   lolcat -F 0.3  # Slower color transition
   lolcat -F 0.1  # Faster color transition

4. Edit the fallback ASCII art: Modify the hardcoded art in the show_animation() function

Troubleshooting

Hook not showing ASCII art?

• Make sure the hook is executable: chmod +x .git/hooks/pre-push
• Install figlet and lolcat for best results: brew install figlet lolcat
• Hook still works without them - uses fallback ASCII art
• Test manually: ./test.sh

Want rainbow colors?

• Install lolcat: brew install lolcat (macOS) or gem install lolcat (any OS)
• Or just install figlet - still looks good without colors

No audio/video playing?

• Audio/video is optional - ASCII art works without it
• Add media files to the media/ directory
• For video: Install mpv (brew install mpv)
• For audio: System audio players are used automatically
• On Linux audio, install one of: ffmpeg, mpg123, sox, or alsa-utils

Want video instead of audio?

• Install mpv: brew install mpv (macOS) or sudo apt install mpv (Linux)
• Add video files (.webm, .mp4, .mkv, .avi) to the media/ directory
• Videos play in a large centered window (50% of screen)
• Video takes priority over audio when mpv is available

Uninstallation

Remove the hook:

rm .git/hooks/pre-push

License

MIT License - See LICENSE file for details.

Open source and available for anyone to use and enjoy!