gource
Visualize software repository history as an animation
TLDR
Run gource in a directory (if it isn't the repository's root directory, the root is sought up from there)
Run gource in the current directory, with a custom output resolution
Specify how long each day should be in the animation (this combines with -c, if provided)
Use fullscreen mode and a custom background color
Specify the animation title
Pause the animation
Adjust simulation speed
Display help
SYNOPSIS
gource [options] [path]
PARAMETERS
--viewport WIDTHxHEIGHT
Sets the viewport width and height.
--output-ppm-stream FILENAME
Outputs the animation as a PPM stream to the specified file. Useful for piping to video encoders.
--start-date DATE
Specifies the date to start the animation from.
--stop-date DATE
Specifies the date to stop the animation at.
--seconds-per-day SECONDS
Sets the number of seconds of animation time that should represent one day of real-world time.
--multi-sampling
Enables multi-sampling for smoother visuals.
--user-image-dir DIRECTORY
Specifies a directory containing images to use for users.
--file-idle-time SECONDS
Sets the time a file stays visible after being modified. Default: 3
--max-file-lag SECONDS
maximum delay a file event can be delayed by (useful for importing slow logs). Default: 30
--max-user-speed SECONDS
Maximum speed a user can travel. Default: 10000
--elasticity FLOAT
How tightly the users will follow the files that move. Default: 0.2
--date-format FORMAT
Format string for date parsing. Default: %Y-%m-%d %H:%M:%S
--auto-skip-seconds SECONDS
Amount of time the animation will automatically fast forward if there are no events.
--follow-user USERNAME
Follow one user and place in the center of the screen
--bloom-intensity FLOAT
Sets the bloom intensity. Default: 0.2
--bloom-multiplier FLOAT
Sets the bloom multipler. Default: 0.2
[path]
The path to the Git repository or log file.
DESCRIPTION
Gource is a software version control visualization tool. It animates a software project's directory tree over time, showing commits and modifications as colorful fountains of activity. Each developer becomes a 'node' that creates new files (appearing as new 'leaves') and edits existing ones. The size and color of the leaves usually represents the file size or the nature of the change. Gource is particularly useful for understanding project history, identifying active areas of development, and visualizing collaboration patterns. It's often used to create impressive videos of software project evolution. Its intuitive visual style makes it attractive to a broad audience and allows a quick understanding of the development history.
CAVEATS
Gource requires a log file containing the project's history. For Git repositories, the 'git log' command can be used to generate a suitable log.
GENERATING LOG FILES
For Git repositories, a suitable log file can be created using the command:git log --pretty=format:'%aN %ad %s' --date=short --numstat --summary > log.txt
You should adjust parameters according to your needs.
COLOR MAPPING
The colors of the files in Gource can be configured via a custom color scheme, making it possible to highlight files based on type, size, age, or any other criteria. Color configuration is documented on the official Gource page and is useful to emphasize important changes in your visualization.
PERFORMANCE
For large repositories, generating the log file and running Gource can be resource-intensive. Consider optimizing the log generation process and using the `--viewport` option to reduce the rendering resolution if performance is a problem.
HISTORY
Gource was created by Rodrigo Toledo in 2006 and has seen continuous development and widespread adoption since. It was initially designed to visualize the evolution of open-source projects. Over time, it gained popularity for its ability to present complex project histories in an engaging and understandable way. It has been featured in many software development presentations and online videos.