# Gource Gource is an open source software version control visualization tool. It creates animated visualizations of source code repositories, showing the evolution of a project over time as developers work on files and directories. The visualization displays the repository as a tree structure where files appear as colored nodes and developers as moving avatars. Watching a Gource video reveals patterns in development: where activity concentrates, how the codebase grows, and who works on what. ## Key Features - **Animated tree visualization**: Files and directories as an expanding tree - **Developer avatars**: Each contributor shown with their Gravatar or custom image - **Time-lapse playback**: Compress years of development into minutes - **Customizable**: Colors, speed, camera behavior, labels, and more - **Video export**: Generate MP4/WebM videos via FFmpeg - **Multi-repo support**: Combine multiple repositories in one visualization ## Supported Version Control Systems - [[Git]] - Mercurial - Bazaar - SVN (via git-svn or custom log) - Custom log formats ## Basic Usage ### Quick Visualization ```bash cd /path/to/repo gource ``` ### Common Options ```bash # Set resolution and run time gource -1280x720 --seconds-per-day 0.5 # Hide specific elements gource --hide filenames,dirnames,usernames # Custom date range gource --start-date "2023-01-01" --stop-date "2023-12-31" # Custom title gource --title "My Project History" ``` ### Export to Video 4K example: ``` gource -3840x2160 -o - | ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i - -vcodec libx264 -preset slow -pix_fmt yuv420p -crf 18 -threads 0 gource-4k.mp4 ``` Other example (1080p) ``` gource -1920x1080 --hide usernames,filenames --file-idle-time 0 --max-user-speed 1000 --seconds-per-day 0.05 --max-files 100000 --max-file-lag 0.1 --file-filter "\.obsidian","\.github",".history","\.idea","\.obsidian","\.smart-env","\.stfolder","\.vaultexplorer","copilot-custom-prompts","node_modules" --auto-skip-seconds 1 --bloom-multiplier 0.90 --bloom-intensity 1.2 --background 37404c -o - | ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i --vcodec libx264 -preset ultrafast -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 gource.mp4 ``` Useful settings: - `--max-file-lag 0.1` - `-e 0.5` - `--camera-mode track` ## Customization Options | Option | Description | |--------|-------------| | `--seconds-per-day` | Speed of playback | | `--auto-skip-seconds` | Skip idle periods | | `--file-idle-time` | How long files stay visible | | `--max-files` | Limit visible files | | `--user-image-dir` | Custom avatar directory | | `--background-colour` | Background color (hex) | | `--font-size` | Label font size | | `--camera-mode` | overview, track | And more! ## Use Cases - **Project retrospectives**: Visualize a year of development - **Presentations**: Show project evolution to stakeholders - **Team building**: Celebrate contributions from all developers - **Documentation**: Create visual history of open source projects - **Social media**: Share engaging development videos ## Tips ## References - Official website: https://gource.io/ - Documentation: https://github.com/acaudwell/Gource/wiki - GitHub repository: https://github.com/acaudwell/Gource - Controls: https://github.com/acaudwell/Gource/wiki/Controls ## Related - [[Git]] - [[Version Control]]