gource-organisation

Creating an organisation-wide gource animation

Gource is a tool that creates animations of the changes in a projects.

The most common usage scenario is to show git commits over a period of time, but it can display any kind of information¹ that follow the defined format.

Although gource is easy to use when called for a single repository, it can be a bit more complicated to create an animation for an organisation with multiple repositories.

This guide will show you how to create an organisation-wide gource animation, both an all-hands overview, and individual videos per contributor.

• 📄 Getting Gource

  • Installing Gource
    • On Linux
    • On macOS
    • On Windows
  • Using Docker
  • Install from source

• Creating Logs

  • Preparations
    • 📄 Cloning all repositories
    • 📄 Adding a .mailmap file
      • Creating a .mailmap file
      • Checking the .mailmap file
      • Using the .mailmap file
  • 📄 Generating a Gource log file
    • Generating log files for all repositories
  • 📄 Cleaning up the log files
    • Adding a common root
    • Removing submodule / subtree
    • Removing third-party code
    • Dealing with deprecated repositories
  • 📄 Combining the log files

• Calling Gource

  • Preparations
    • 📄 Creating avatars
    • 📄 Creating a Gource caption file
    • 📄 Creating Gource configuration
      • The caption file format
      • Generating a caption file
      • Manually adding entries to the caption file

To keep things clearly arranged, the following directory structure is used:

project/
  ├── avatars/
  │   ├── ...
  │   └── default.png (or default.jpg)
  ├── logs/
  │   ├── clean/
  │   ├── full/               <-- To be filled by gource
  │   ├── with-paths-ignored/
  │   ├── with-root/
  │   ├── combined.log
  │   ├── ignore-paths.txt
  │   └── ignore-vendors.txt
  ├── repos/
  │   ├── ...
  │   └── repository-name/
  ├── videos/           <-- To be filled by gource
  │   └── user/
  ├── captions.txt
  ├── deprecated-repos.txt
  ├── gource.config
  ├── logo.png
  └── .mailmap

Bugzilla, DocuWiki, JIRA, MediaWiki but there are also visualizations of the COVID19 Corona virus.

1. Some examples form the Custom Log Format page are ↩