gource

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]

$ gource -[width]x[height]

$ gource [[-s|--seconds-per-day]] [seconds]

$ gource [[-f|--fullscreen ]] [[-b|--background-colour]] [hex_color_code]

$ gource --title [title]

$ <Space>

$ <[+|-]>

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

gource [OPTIONS] [PATH_TO_REPOSITORY | LOG_FILE]

Examples:
gource ~/my_git_repo
git log --pretty=format:':%ct|%an|%s' --reverse | gource --log-format custom

-s , --seconds-per-day
    Set the simulation speed, representing how many seconds of development time pass per second of real time.

-a , --auto-skip-seconds
    Automatically skip periods of inactivity longer than the specified seconds.

-r , --repository-root
    Specify the root directory of the repository, useful if Gource can't automatically detect it.

-p , --start-position
    Start playback at a specific percentage (0.0 to 1.0) of the total repository history.

-e , --start-date
    Begin the visualization from a specific date.

-D , --stop-date
    End the visualization at a specific date.

-U

Gource is an animated visualization tool for software version control repositories, transforming static commit logs into a captivating real-time display. It graphically represents the project's history as a dynamic tree structure, where files and directories are nodes that appear, disappear, and change over time. Developers, depicted as user avatars or names, fly into the tree, interact with files, and contribute their changes, with file modifications highlighted visually. Gource supports various version control systems including Git, Mercurial, SVN, and Bazaar, and can also process custom log formats. This provides a unique and intuitive insight into a project's evolution, illustrating bursts of activity, file additions, deletions, and modifications. It vividly demonstrates the collaborative nature of software development and is frequently employed to generate compelling project overview videos, making complex development histories easily understandable and engaging.

Gource can be resource-intensive for very large repositories with extensive history, potentially leading to slow frame rates or high memory usage. It relies on accurate version control system logs; malformed logs can cause unexpected behavior. Generating high-quality video output often requires post-processing with external tools like FFmpeg. The default visualization may become cluttered for projects with very high concurrent activity or numerous files, necessitating parameter tuning.

Gource is highly versatile due to its support for custom log formats, allowing users to visualize data from sources beyond standard VCS systems. The custom format typically involves lines structured as :timestamp|author|type|file/directory, where type can be A (add), M (modify), or D (delete). This flexibility enables the creation of visualizations from virtually any time-series data related to file or directory changes, making it a powerful tool for various data analysis scenarios.

For a more personalized and clear visualization, Gource supports displaying custom images (avatars) for each user. By placing PNG or JPG image files named after the commit author (e.g., john.doe.png) in a directory specified by the --user-image-dir option, users can enhance the visual appeal and easily identify who is contributing to the project at a glance.

While Gource provides real-time rendering, one of its primary use cases is exporting the visualization to a video file for sharing or presentation. This is commonly achieved by piping Gource's raw PPM stream output to a powerful video encoder like FFmpeg. This allows users to create high-quality, shareable videos of their project's entire development history, complete with sound if desired, for archival or promotional purposes.

Gource was created by Andrew Light in 2009. It was initially designed to visualize Git repositories but quickly expanded to support other version control systems like Mercurial, SVN, and Bazaar. Its development was driven by the desire to provide a visually engaging and intuitive way to understand project evolution and developer contributions over time. Since its inception, it has gained popularity in open-source communities and businesses alike for its unique ability to bring static version control logs to life.

git-log(1), svn-log(1), tig(1), ffmpeg(1)