4 releases
0.3.1 | Dec 31, 2023 |
---|---|
0.3.0 | Dec 31, 2023 |
0.2.1 | Dec 29, 2023 |
0.2.0 | Dec 29, 2023 |
#1456 in Development tools
335KB
745 lines
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
Dependencies
~21–33MB
~558K SLoC