Gource(1)

📦
version 0.56 · 4 versions
, in alpine 3.24, arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking

✨ Gource(1) ✨

okay bestie, welcome to the Gource(1) manual page! 💖 This is part 1, and we're about to make your terminal look like a whole forest of commits. 🌳✨

🌸 NAME 🌸

Gource — a software version control visualization. periodt. 👑

🦋 SYNOPSIS 🦋

gource [options] [path]

💅 DESCRIPTION 💅

okay so gource is an OpenGL-based 3D visualisation tool for source control repositories. it's giving main character energy for your git log. 😭

The repository is displayed as a tree where the root of the repository is the centre, directories are branches and files are leaves. Contributors to the source code appear and disappear as they contribute to specific files and directories. it's literally a whole ecosystem, iykyk. 🌈

🎀 REQUIREMENTS 🎀

gource requires a OpenGL capable video card to run. no cap, your GPU gotta be serving. 💅

👑 OPTIONS 👑

  • -h, --help — Help ('-H' for extended help). so if you need the extra tea, hit -H. ☕
  • -WIDTHxHEIGHT, --viewport WIDTHxHEIGHT — Set the viewport size. If -f is also supplied, will attempt to set the video mode to this also. Add ! to make the window non-resizable. so you can lock it down, periodt. 🔒
  • -f — Fullscreen. whole screen, no distractions. 👑
  • --screen SCREEN — Set the number of the screen to display on. for my multi-monitor girlies. 🖥️
  • --high-dpi — Request a high DPI display when creating the window.

On some platforms such as MacOS, the window resolution is specified in points instead of pixels. The --high-dpi flag may be required to access some higher resolutions.

E.g. requesting a high DPI 800x600 window may produce a window that is 1600x1200 pixels. so crisp, so slay. ✨

  • --window-position XxY — Initial window position on your desktop which may be made up of multiple monitors.

This will override the screen setting so don't specify both. pick a lane bestie. 🛑

  • --frameless — Frameless window. clean, minimal, aesthetic. 🎀
  • --transparent — Make the background transparent. Only really useful for screenshots. for the gram. 📸
  • --start-date "YYYY-MM-DD hh:mm:ss +tz" — Start with the first entry after the supplied date and optional time.

If a time zone offset isn't specified the local time zone is used.

Example accepted formats:

"2012-06-30"
"2012-06-30 12:00"
"2012-06-30 12:00:00 +12"

so you can time travel, but only forward. ⏳

  • --stop-date "YYYY-MM-DD hh:mm:ss +tz" — Stop at the last entry prior to the supplied date and optional time.

Uses the same format as --start-date. so you can cut it off, no cap. ✂️

  • -p, --start-position POSITION — Begin at some position in the log (between 0.0 and 1.0 or 'random'). so you can skip to the good part. 🎯
  • --stop-position POSITION — Stop (exit) at some position in the log (does not work with STDIN). note: no STDIN, bestie. 🚫
  • -t, --stop-at-time SECONDS — Stop (exit) after a specified number of seconds. set a timer, queen. ⏰
  • --stop-at-end — Stop (exit) at the end of the log / stream. natural ending, periodt. 🎬
  • --loop — Loop back to the start of the log when the end is reached. it's giving rerun energy. 🔁
  • --loop-delay-seconds SECONDS — Seconds to delay before looping. a little pause for dramatic effect. ⏸️
  • -a, --auto-skip-seconds SECONDS — Automatically skip to next entry if nothing happens for a specified number of seconds. so it doesn't get boring. 💤
  • -s, --seconds-per-day SECONDS — Speed of simulation in seconds per day. time is fake, go fast. ⚡
  • --realtime — Realtime playback speed. no fast-forward, just vibes. 🕰️
  • --no-time-travel — Use the time of the last commit if the time of a commit is in the past. so no going backwards, only forwards. ⏩
  • --author-time — Use the timestamp of the author instead of the timestamp of the committer. author rights, periodt. ✍️
  • -c, --time-scale SCALE — Change simulation time scale. This affects the movement speed of user avatars.

E.g. 0.5 for half speed, 2 for double speed. so you can slow it down or speed it up, your choice. 🐢🐇

  • -i, --file-idle-time SECONDS — Time in seconds files remain idle before they are removed or 0 for no limit. 0 means never delete, hoarder energy. 🗂️
  • --file-idle-time-at-end SECONDS — Time in seconds files remain idle at the end before they are removed. for the grand finale. 🎆
  • -e, --elasticity FLOAT — Elasticity of nodes. boing boing. 🌀
  • -b, --background-colour FFFFFF — Background colour in hex. pick your aesthetic. 🎨
  • --background-image IMAGE — Set a background image. serve looks. 🖼️
  • --title TITLE — Set a title. name it, own it. 👑
  • --font-file FILE — Specify the font. Should work with most font file formats supported by FreeType, such as TTF and OTF, among others. so you can be extra. ✒️
  • --font-scale SCALE — Scale the size of all fonts. big mood or small mood. 🔍
  • --font-size SIZE — Font size used by the date and title. for the date and title specifically. 📅
  • --file-font-size SIZE — Font size of filenames. files need love too. 📄
  • --dir-font-size SIZE — Font size of directory names. directories are important. 📁
  • --user-font-size SIZE — Font size of user names. shoutout to the users. 👥
  • --font-colour FFFFFF — Font colour used by the date and title in hex. make it pop. 💖
  • --key — Show file extension key. a little legend, iykyk. 🗝️
  • --logo IMAGE — Logo to display in the foreground. branding, bestie. 🏷️
  • --logo-offset XxY — Offset position of the logo. move it where you want. 📍
  • --date-format FORMAT — Specify display date string (strftime format). format it your way. 📆
  • --log-command VCS — Show the log command used by gource (git,svn,hg,bzr,cvs2cl). so you can see the tea. ☕
  • --log-format VCS — Specify format of the log being read (git,svn,hg,bzr,cvs2cl,custom). Required when reading from STDIN. no format, no STDIN. 🚫
  • --git-branch — Get the git log of a branch other than the current one. branch out, queen. 🌿
  • --follow-user USER — Have the camera automatically follow a particular user. main character tracking. 🎥
  • --highlight-dirs — Highlight the names of all directories. directories getting the spotlight. ✨
  • --highlight-user USER — Highlight the names of a particular user. one user, all the attention. 🌟
  • --highlight-users — Highlight the names of all users. everyone's a star. 🌠
  • --highlight-colour FFFFFF — Font colour for highlighted users in hex. colour for the chosen ones. 💛
  • --selection-colour FFFFFF — Font colour for selected users and files. selection colour, slay. 💙
  • --filename-colour FFFFFF — Font colour for filenames. filenames in colour. 💚
  • --dir-colour FFFFFF — Font colour for directories. directories in colour. 💜
  • --dir-name-depth DEPTH — Draw names of directories down to a specific depth in the tree. how deep do you want to go? 🕳️
  • --dir-name-position FLOAT — Position along edge of the directory name (between 0.1 and 1.0, default is 0.5). default 0.5, but you can move it. 🎚️
  • --filename-time SECONDS — Duration to keep filenames on screen (>= 2.0). at least 2.0, no cap. ⏱️
  • --file-extensions — Show filename extensions only. just the extensions, periodt. 📎
  • --file-extension-fallback — Use filename as extension if the extension is missing or empty. fallback realness. 🆘
  • --file-filter REGEX — Filter out file paths matching the specified regular expression. bye bye, files. 👋
  • --file-show-filter REGEX — Show only file paths matching the specified regular expression. only the chosen files. 🎯
  • --user-filter REGEX — Filter usernames matching the specified regular expression. not today, user. 🚫
  • --user-show-filter REGEX — Show only usernames matching the specified regular expression. only the VIPs. 🌟
  • --user-image-dir DIRECTORY — Directory containing .jpg or .png images of users (eg "Full Name.png") to use as avatars. give everyone a face. 🖼️
  • --default-user-image IMAGE — Path of .jpg to use as the default user image. default face, periodt. 👤
  • --fixed-user-size — Forces the size of the user image to remain fixed throughout. no resizing, keep it consistent. 📏
  • --colour-images — Colourize user images. add some colour, bestie. 🌈
  • --crop AXIS — Crop view on an axis (vertical,horizontal). crop it, own it. ✂️
  • --padding FLOAT — Camera view padding. give it some space. 🌌
  • --multi-sampling — Enable multi-sampling. smooth edges, slay. ✨
  • --no-vsync — Disable vsync. let it run wild. 🏃
  • --bloom-multiplier FLOAT — Adjust the amount of bloom. more bloom, more drama. 🌸
  • --bloom-intensity FLOAT — Adjust the intensity of the bloom. turn up the glow. 💡
  • --max-files NUMBER — Set the maximum number of files or 0 for no limit. Excess files will be discarded. 0 means unlimited, but excess gets the boot. 🥾
  • --max-file-lag SECONDS — Max time files of a commit can take to appear. Use -1 for no limit. -1 means no limit, periodt. ⏳
  • --max-user-speed UNITS — Max speed users can travel per second. speed limit, bestie. 🚗
  • --user-friction SECONDS — Time users take to come to a halt. how long to stop, physics. 🛑
  • --user-scale SCALE — Change scale of user avatars. big avatars or small avatars. 🔍
  • --camera-mode MODE — Camera mode (overview,track). choose your view. 🎥
  • --disable-auto-rotate — Disable automatic camera rotation. stop spinning, i'm dizzy. 🌀
  • --disable-input — Disable keyboard and mouse input. no touchy. 🚫
  • --hide DISPLAY_ELEMENT — Hide one or more display elements from the list below:
    • bloom - bloom effect
    • date - current date
    • dirnames - names of directories
    • files - file icons
    • filenames - names of files
    • mouse - mouse cursor
    • progress - progress bar widget
    • root - root directory of the tree
    • tree - animated tree structure
    • users - user avatars
    • usernames - names of users

Separate multiple elements with commas (eg "mouse,progress"). hide what you don't need, periodt. 🙈

  • --hash-seed SEED — Change the seed of hash function. shake it up. 🎲
  • --caption-file FILE — Caption file (see Caption Log Format). captions for the drama. 📝
  • --caption-size SIZE — Caption size. big captions or small captions. 🔠
  • --caption-colour FFFFFF — Caption colour in hex. colour your words. 🎨
  • --caption-duration SECONDS — Caption duration. how long they stay. ⏳
  • --caption-offset X — Caption horizontal offset (0 to centre captions). 0 to centre, periodt. ↔️
  • -o, --output-ppm-stream FILE — Output a PPM image stream to a file ('-' for STDOUT).

This will automatically hide the progress bar initially and enable 'stop-at-end' unless other behaviour is specified. so it does some stuff automatically, noted. 📤

  • -r, --output-framerate FPS — Framerate of output (25,30,60). Used with --output-ppm-stream. pick 25, 30, or 60. 🎞️
  • --output-custom-log FILE — Output a custom format log file ('-' for STDOUT). custom log, custom vibes. 📄
  • --load-config CONFIG_FILE — Load a config file. load it up. 📂
  • --save-config CONFIG_FILE — Save a config file with the current options. save your settings, queen. 💾
  • --path PATH
  • path — Either a supported version control directory, a pre-generated log file (see log commands or the custom log format), a Gource conf file or '-' to read STDIN.

If path is omitted, gource will attempt to read a log from the current directory. so if you don't give a path, it tries the current directory. 🏠

🧚 Git, Bazaar, Mercurial and SVN Examples 🧚

View the log of the repository in the current path:

gource

View the log of a project in the specified directory:

gource my-project-dir

For large projects, generating a log of the project history may take a long time. For centralized VCS like SVN, generating the log will put load on the central VCS server. so be nice to the server, bestie. 😭

In these cases, you may like to save a copy of the log for later use. smart move. 🧠

You can generate a log in the VCS specific log format using the --log-command VCS option:

cd my-svn-project
`gource --log-command svn` > my-svn-project.log
gource my-svn-project.log

You can also have Gource write a copy of the log file in its own format:

gource --output-custom-log my-project-custom.log

🍓 CVS Support 🍓

Use 'cvs2cl' to generate the log and then pass it to Gource:

cvs2cl --chrono --stdout --xml -g-q > my-cvs-project.log
gource my-cvs-project.log

okay so that's how you turn your CVS history into a snackable log, bestie 💅

🦋 Custom Log Format 🦋

if you're rolling with something that isn't on the supported list, gource still gotchu. there's a custom log format that's pipe (|) delimited, and it's giving very choose-your-own-adventure. here's the tea:

  • timestamp — when the update went down, either an ISO 8601 or a unix timestamp, no cap.
  • username — the name of the user who made the update, aka the main character.
  • type — a single character for what kind of update it was: (A)dded, (M)odified, or (D)eleted.
  • file — the path of the file that got updated.
  • colour — a colour for the file in hex (FFFFFF) format. this one's optional, so you can skip it if you're feeling minimal.

🌸 Caption Log Format 🌸

gource can also drop captions along the timeline, like little commentary track moments. just specify a caption file using --caption-file, and format it like this pipe (|) delimited situation:

  • timestamp — an ISO 8601 or unix timestamp of when to display the caption.
  • caption — the caption itself.

🎀 Recording Videos 🎀

want to record your gource masterpiece? there's a whole guide on the homepage with examples of recording videos with gource:

https://github.com/acaudwell/Gource/wiki/Videos

🌈 More Information 🌈

for guides and examples of using gource with various version control systems, slide into the gource homepage:

http://gource.io

💻 INTERFACE 💻

the time shown in the top left of the screen is set initially from the first log entry read and is incremented according to the simulation speed (--seconds-per-day).

pressing SPACE at any time will pause/resume the simulation. while paused, you can use the mouse to inspect the detail of individual files and users. it's giving detective mode 🔍

TAB cycles through selecting the current visible users.

the camera mode, either tracking activity or showing the entire code tree, can be toggled using the Middle mouse button.

you can drag the left mouse button to manually control the camera. the right mouse button rotates the view. slay.

Interactive keyboard commands:

  • (V) — Toggle camera mode
  • (C) — Displays Gource logo
  • (K) — Toggle file extension key
  • (M) — Toggle mouse visibility
  • (N) — Jump forward in time to next log entry
  • (S) — Randomize colours
  • (D) — Toggle directory name display mode
  • (F) — Toggle file name display mode
  • (U) — Toggle user name display mode
  • (G) — Toggle display of users
  • (T) — Toggle display of directory tree edges
  • (R) — Toggle display of root directory edges
  • (<>) — Adjust time scale / user avatar movement speed
  • (+-) — Adjust simulation speed
  • (Keypad +-) — Adjust camera zoom
  • (TAB) — Cycle through visible users
  • (F12) — Screenshot
  • (Alt+Enter) — Fullscreen toggle
  • (ESC) — Quit

👑 AUTHOR 👑

Written by Andrew Caudwell

Project Homepage: http://gource.io

Copyright (C) 2009 Andrew Caudwell (acaudwell@gmail.com)

so basically, this program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. (periodt.)

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

🌟 ACKNOWLEDGEMENTS 🌟

Catalyst IT (catalyst.net.nz)

For supporting the development of Gource!

and that's the whole vibe, bestie. this was Gource(1) — go forth and slay your git history ✨💖

📦 where this page comes from