LinuxCommandLibrary

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)

$ gource [path/to/repository]
copy

Run gource in the current directory, with a custom output resolution
$ gource -[width]x[height]
copy

Specify how long each day should be in the animation (this combines with -c, if provided)
$ gource [[-s|--seconds-per-day]] [seconds]
copy

Use fullscreen mode and a custom background color
$ gource [[-f|--fullscreen ]] [[-b|--background-colour]] [hex_color_code]
copy

Specify the animation title
$ gource --title [title]
copy

Pause the animation
$ <Space>
copy

Adjust simulation speed
$ <[+|-]>
copy

Display help
$ gource [[-h|--help]]
copy

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.

SEE ALSO

git(1), svn(1), hg(1)

Copied to clipboard