Rource

What is it?

Rource is a tool to generate a Gource log file from a git repository or a directory containing git repositories.

If you don't know what Gource is you can check it out here: https://github.com/acaudwell/Gource

It's a tool to generate a cool visualisation from a log file, usually a Source Control system, like this:

How do I use it?

Give rource a path to a git repository or a directory containing repositories and it will generate a Gource log file.

You can control whether it should recursively search for repositories or not, and you can also specify which repositories to include or exclude.

Rource also supports username aliases, so you can map various git usernames to cleaner, presentable names to display in Gource. It also supports shell expansion, so you can use ~ to refer to your home directory if you prefer.

Examples

Scan a folder for git repositories recursive, apply two aliases and output to a file:

rource -p ~/source/my-github-org -r --alias "AdamLeyshon::WelshProgrammer" --alias "SomeOtherUsername::WelshProgrammer" -o output.txt

Scan a folder for git repositories recursive, apply two aliases and pipe directly to Gource:

rource -p ~/source/my-github-org -r | gource - --log-format custom

Generate log for a single repository and pipe directly to Gource:

rource -p ~/source/my-github-org/my-repo | gource - --log-format custom

Generate log for this repository and output to a file:

rource -p ./ -o output.txt

How do I get it?

Install from crates.io

It should be as simple as:

cargo install rource

Building/Installing from source

git clone https://github.com/AdamLeyshon/rource.git 
cd rource

# You can either install it
cargo install --path .

# Or build it, the binary will be in ./target/release/rource
cargo build --release

Available options

Rource! A tool to convert git logs into a format that can be used by Gource.

WARNING: When used with large quantities of repositories or a repository with many commits, Rource can generate very large files.
In some cases you may need to use the --use-merge-sort option, please read the documentation for this option for more info.

Usage: rource [OPTIONS] --path <PATH>

Options:
    -p, --path <PATH>
        The path to the git repository/repositories
    
    -r, --recursive
        Recursively search for repositories, by default all repositories in <PATH> will be included
    
    -i, --include <INCLUDE>
        Used with recursive, only process these repositories, cannot be used with --exclude
    
    -e, --exclude <EXCLUDE>
        Used with recursive, exclude these repositories from processing, cannot be used with --include
    
    -o, --output <OUTPUT>
        Output file, writes to stdout if not specified
    
    -a, --alias <ALIAS>
        Add an alias for a user, the format is <USERNAME>::<REPLACEMENT>,
        If a username contains pipes (|), they are automatically be replaced with '#' before aliases are applied,
        If you want to alias 'Some|User', your alias should be 'Some#User::SomeUser'.
        You can specify this option multiple times
    
    -m, --use-merge-sort
        Use Merge Sort, required when processing large quantities of commits.
        Be aware that when using the merge sort, you will need at least 3x the size of the final log file in free disk space.
        For example, when used against the Rust repository, the final output is 64GB but the temporary space needed is upto 192GB.
        Please also read the documentation for --sort-chunk-size and --temp-file-location for additional controls
    
    --sort-chunk-size <SORT_CHUNK_SIZE>
        Chunk size in Megabytes (Min: 64 MB), Merge sort will try to limit RAM usage to this amount, however it is not a hard limit and should be viewed as a hint, by default it will use 4 GB. Depending on the number of commits, more RAM will help speed up the sort/merge phase
    
    -t, --temp-file-location <TEMP_FILE_LOCATION>
        Location to store temporary files, by default this will randomly named directory in the current working path, if the program is interrupted you may need to delete this directory manually
    
    -z, --max-changeset-size <MAX_CHANGESET_SIZE>
        Commits with a changeset larger than this will be filtered out, this is useful for ignoring commits that are likely to be merges, tags or CI/CD commits
    
    -h, --help
        Print help (see a summary with '-h')
    
    -V, --version
        Print version

Tips

GitHub Organisation

If you work in an organisation with many repositories on GitHub you use the GH CLI to clone them all locally and then use rource to generate a log file for all of them.:

# Make a directory to clone all the repos into
mkdir ~/source/my-github-org
cd ~/source/my-github-org

# Login first if you haven't already
gh auth login

# Then clone all the repos, depending on the size, this may take a long time!
gh repo list <your-org-name> --limit 4000 | while read -r repo _; do
  gh repo clone "$repo" "$repo"                                                         
done

# Then generate the log file, plus an example to set an alias for a user and exclude an external repo 
rource -p ~/source/my-github-org -r --alias "GithubUsername::Friendly Name" -e "ADependencyLibrary" -o output.txt