My favorites | Sign in
Project Home Downloads Wiki Issues Source
An overview of the interactive controls and command line options
Updated Apr 21, 2013 by

Note: some options may require the latest version of Gource.

Check out the Videos section for examples and instructions for creating your own videos with Gource.

Display Settings

You can set the screen resolution with -WIDTHxHEIGHT and switch to full-screen mode with -f. To set the view to full-screen 720p:

gource -f -1280x720

For additional anti-aliasing use the --multi-sampling option.

Camera Controls

Camera Mode

Gource has two camera modes:

  • overview - keeps the entire repository in view.
  • track - follows the current active users or the selected user.

The default mode is 'overview'. To set the camera mode to 'track':

gource --camera-mode track

You can also toggle the mode in Gource with the V key and the middle mouse button. Pressing Tab cycles though the current visible users.


Dragging the left mouse button on the background pans the camera. This will also disable automatic camera movement until you toggle the camera mode. You can also move the camera with the arrow keys.


As of 0.27, Gource will automatically rotate the view to make best use of the available screen space. If this is not to your liking, you can turn this off with --disable-auto-rotate.

You can manually rotate the view by dragging right mouse button on the background. This will also disable automatic camera rotation until you toggle the camera mode.


You can change the maximum zoom distance with the mouse wheel.

Time-line / Chronology


You can seek to any point in the project using the time-line widget that appears along the bottom of the screen when the mouse passes over it. Mousing over the time-line shows the date at that position in the history file.


Pause the action by pressing space. While paused, you can still move the camera around and inspect the details of files and users.

Start / Stop Position

Use --start-position and --stop-position to specify the period of the project history to display. The argument is a fraction of the total length of the project history file:

gource --start-position 0.5 --stop-position 0.75

Seconds Per Day

Seconds per day controls the amount of time Gource will take to display each day in the log file (10 seconds by default).

gource --seconds-per-day 1

As a convenience, the option --realtime sets seconds-per-day to 60*60*24.

Auto Skip Seconds

Some projects may have gaps in activity in the span of days or weeks. To avoid the boring bits, Gource will advance to the next entry (after 3 seconds by default) if nothing is happening.

To change the auto skip seconds value:

gource --auto-skip-seconds 1

The sister command --disable-auto-skip may be used to turn this feature off:

gource --disable-auto-skip

File Idle Time

By default, Gource 'expires' files which haven't been touched by a user in the 60 seconds. You can change the amount of time files remain without changing with:

--file-idle-time SECONDS

To turn expiring files off:

--file-idle-time 0

File Lag

Gource doesn't actually apply updates immediately as they come up in the log, instead the user will move towards the area of the new files before adding them. This is easier to follow but it also means if you are using a small value for 'seconds-per-day', it can get quite far behind.

You can change the time limit for files to be added in seconds (default 5) with --max-file-lag SECONDS:

gource --max-file-lag 0.1

Above, files must appear within 0.1 seconds (100ms).


Legend / File Extension Key

Pressing K or launching gource with --key enables a file extension key, showing the colours used for each file extension and the current number of files with that extension listed in descending order:

gource --key


Gource has some command line options to control the appearance of the 'light bloom' effect that appears around directories. You can affect the radius of the bloom using --bloom-multiplier, and the intensity using --bloom-intensity.

To get double the radius and double the normal intensity you would use:

gource --bloom-multiplier 2.0 --bloom-intensity 1.5

If you're sick of the bloom effect, you can turn it off with --disable-bloom.


Elasticity is a fun if somewhat pointless effect that controls how 'rubbery' directory branches behave when they have a force applied to them:

gource -e 0.5


The background colour can be set with the --background option followed by a colour in hex format (like in HTML):

gource --background 555555

This will set the background colour to a darkish grey

You can set the alpha channel to be transparent with --transparent. This is useful if you want to take screenshots (F12) and manipulate them in image editing software. Note ppm output does not have an alpha channel so will not be affected.

To set a background image:

gource --background-image background.png


Press S to cycle through alternate colours for files and users. You can also specify an alternate colour hashing 'seed' on the command line with --hash-seed.

Date Format

Change the strftime format string Gource uses to display the current time (See strftime manual for valid format strings).

gource --date-format "%D"


You can change the default font size and colour of the timer and titles with:

gource --font-size 18 --font-colour FFFF00


Set a logo to appear in the foreground:

gource --logo logo.png

The logo position can be changed with --logo-offset XxY.


Set a title to appear in the bottom left corner of the screen:

gource --title "My Project"

Hiding Elements

Sometimes it's hard to see the forest through the trees. To cull the brush:

gource --hide bloom,date,dirnames,files,filenames,mouse,progress,tree,users,usernames

(your screen should now be blank).

Comment by asbjornu, Feb 14, 2012

The --date-format argument seems to not adjust how dates are displayed, but instead how they are parsed from the log. I at least get the error message gource: unsupported log format (you may need to regenerate your log file) when I try something like --date-format "%Ec".

Comment by, Jul 29, 2012

good job, thank you very much.

Comment by, Oct 22, 2012

@asbjomu, the following works for me and is preferred to keep the date string from wobbling around:

--date-format "%Y-%m-%d %H:%M:%S"

Comment by, Oct 26, 2012

How to keep all the users visible all the time? Thanks!

Comment by project member, Oct 27, 2012

'--camera-mode track' might be what you want.

Comment by, Apr 21, 2013

Thanks for the hard work. Btw, --logo-offset should be #x# now, not #y# :)

Comment by project member, Apr 21, 2013


Comment by, Jun 14, 2013

This is wonderful, thank you!

Comment by, Jun 15, 2013

could use tips for keeping file size down, the ppm file ate up my 1TB hdd

Comment by, Jul 11, 2013

Give a life to code. Yes We Can :)

Comment by, Aug 14, 2013

Thanks a lot for your work, really nice!

Comment by, Feb 28, 2014

I'd love to see a toggle-able version where each node's size is dictated by file size.

Additionally would it be possible to point it to only iterate over one sub-directory?

Comment by, Apr 24, 2014

Beautiful work. Just wondering, is there a way to stop the nodes disappearing at all? I know that file idle control is available, but it doesn't seem to work

Comment by project member, Apr 24, 2014

--file-idle-time 0 should work. Current version does that by default.

Comment by, May 30, 2014

Very nice ! Quick question, is there a way to change font size for filenames ? It looks like font-size only afects date. Keep up the good work !

Comment by project member, May 31, 2014

Sorry there isn't an option to change the file / directory / user font sizes currently.

Comment by, Oct 12, 2014

I'm getting a crazy shaking effect on a couple of the tree branches. Seems to happen once the # of files gets relatively high (> 1,000). Anyone seen this before? I'm using gource 0.42 with this:

gource -1280x768 -b 000000 --bloom-multiplier 0.7 -key --bloom-intensity 0.4 -e 0.1 --auto-skip-seconds 0.25  --max-user-speed 300 --disable-auto-rotate --dir-name-depth 2 --highlight-users --max-file-lag 2 --hide filenames --file-filter "(library/|vendor/|tools/)" --user-scale 3 --user-image-dir .git/avatar/  --date-format "%B %e, %Y" --title "Test" -o - | ffmpeg -y -r 30 -f image2pipe -vcodec ppm -i - -vcodec libx264 -profile:v high -preset medium -tune animation -b:v 2000k -maxrate 3000k -bufsize 4000k -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 test.mp4
Comment by project member, Oct 12, 2014

This will be due to the -e 0.1 argument. Elasticity produces some amusing results but doesn't scale very well.

Sign in to add a comment
Powered by Google Project Hosting