1Gource(1) General Commands Manual Gource(1)
2
6 Gource - a software version control visualization
7
9 gource [options] [path]
10
12 gource is an OpenGL-based 3D visualisation tool for source control
13 repositories.
14 The repository is displayed as a tree where the root of the repository
16 is the centre, directories are branches and files are leaves. Contribu‐
17 tors to the source code appear and disappear as they contribute to spe‐
18 cific files and directories.
19
21 gource requires a OpenGL capable video card to run.
22
24 -h, --help
25 Help ('-H' for extended help).
26 -WIDTHxHEIGHT, --viewport WIDTHxHEIGHT
28 Set the viewport size. If -f is also supplied, will attempt to
29 set the video mode to this also. Add ! to make the window non-
30 resizable.
31 -f Fullscreen.
33 --screen SCREEN
35 Set the number of the screen to display on.
36 --high-dpi
38 Request a high DPI display when creating the window.
39 On some platforms such as MacOS, the window resolution is spec‐
41 ified in points instead of pixels. The --high-dpi flag may be
42 required to access some higher resolutions.
43 E.g. requesting a high DPI 800x600 window may produce a window
45 that is 1600x1200 pixels.
46 --window-position XxY
49 Initial window position on your desktop which may be made up of
50 multiple monitors.
51 This will override the screen setting so don't specify both.
53 --frameless
55 Frameless window.
56 --transparent
58 Make the background transparent. Only really useful for screen‐
59 shots.
60 --start-date "YYYY-MM-DD hh:mm:ss +tz"
62 Start with the first entry after the supplied date and optional
63 time.
64 If a time zone offset isn't specified the local time zone is
66 used.
67 Example accepted formats:
69 "2012-06-30"
71 "2012-06-30 12:00"
72 "2012-06-30 12:00:00 +12"
73 --stop-date "YYYY-MM-DD hh:mm:ss +tz"
75 Stop at the last entry prior to the supplied date and optional
76 time.
77 Uses the same format as --start-date.
79 -p, --start-position POSITION
81 Begin at some position in the log (between 0.0 and 1.0 or 'ran‐
82 dom').
83 --stop-position POSITION
85 Stop (exit) at some position in the log (does not work with
86 STDIN).
87 -t, --stop-at-time SECONDS
89 Stop (exit) after a specified number of seconds.
90 --stop-at-end
92 Stop (exit) at the end of the log / stream.
93 --loop Loop back to the start of the log when the end is reached.
95 --loop-delay-seconds SECONDS
97 Seconds to delay before looping.
98 -a, --auto-skip-seconds SECONDS
100 Automatically skip to next entry if nothing happens for a spec‐
101 ified number of seconds.
102 -s, --seconds-per-day SECONDS
104 Speed of simulation in seconds per day.
105 --realtime
107 Realtime playback speed.
108 --no-time-travel
110 Use the time of the last commit if the time of a commit is in
111 the past.
112 -c, --time-scale SCALE
114 Change simulation time scale.
115 E.g. 0.5 for half speed, 2 for double speed.
117 -i, --file-idle-time SECONDS
119 Time in seconds files remain idle before they are removed or 0
120 for no limit.
121 --file-idle-time-at-end SECONDS
123 Time in seconds files remain idle at the end before they are
124 removed.
125 -e, --elasticity FLOAT
127 Elasticity of nodes.
128 -b, --background-colour FFFFFF
130 Background colour in hex.
131 --background-image IMAGE
133 Set a background image.
134 --title TITLE
136 Set a title
137 --font-file FILE
139 Specify the font. Should work with most font file formats sup‐
140 ported by FreeType, such as TTF and OTF, among others.
141 --font-scale SCALE
143 Scale the size of all fonts.
144 --font-size SIZE
146 Font size used by the date and title.
147 --file-font-size SIZE
149 Font size of filenames.
150 --dir-font-size SIZE
152 Font size of directory names.
153 --user-font-size SIZE
155 Font size of user names.
156 --font-colour FFFFFF
158 Font colour used by the date and title in hex.
159 --key Show file extension key.
161 --logo IMAGE
163 Logo to display in the foreground.
164 --logo-offset XxY
166 Offset position of the logo.
167 --date-format FORMAT
169 Specify display date string (strftime format).
170 --log-command VCS
172 Show the log command used by gource (git,svn,hg,bzr,cvs2cl).
173 --log-format VCS
175 Specify format of the log being read
176 (git,svn,hg,bzr,cvs2cl,custom). Required when reading from
177 STDIN.
178 --git-branch
180 Get the git log of a branch other than the current one.
181 --follow-user USER
183 Have the camera automatically follow a particular user.
184 --highlight-dirs
186 Highlight the names of all directories.
187 --highlight-user USER
189 Highlight the names of a particular user.
190 --highlight-users
192 Highlight the names of all users.
193 --highlight-colour FFFFFF
195 Font colour for highlighted users in hex.
196 --selection-colour FFFFFF
198 Font colour for selected users and files.
199 --filename-colour FFFFFF
201 Font colour for filenames.
202 --dir-colour FFFFFF
204 Font colour for directories.
205 --dir-name-depth DEPTH
207 Draw names of directories down to a specific depth in the tree.
208 --dir-name-position FLOAT
210 Position along edge of the directory name (between 0.1 and 1.0,
211 default is 0.5).
212 --filename-time SECONDS
214 Duration to keep filenames on screen (>= 2.0).
215 --file-extensions
217 Show filename extensions only.
218 --file-extension-fallback
220 Use filename as extension if the extension is missing or empty.
221 --file-filter REGEX
223 Filter out file paths matching the specified regular expres‐
224 sion.
225 --file-show-filter REGEX
227 Show only file paths matching the specified regular expression.
228 --user-filter REGEX
230 Filter usernames matching the specified regular expression.
231 --user-show-filter REGEX
233 Show only usernames matching the specified regular expression.
234 --user-image-dir DIRECTORY
236 Directory containing .jpg or .png images of users (eg "Full
237 Name.png") to use as avatars.
238 --default-user-image IMAGE
240 Path of .jpg to use as the default user image.
241 --fixed-user-size
243 Forces the size of the user image to remain fixed throughout.
244 --colour-images
246 Colourize user images.
247 --crop AXIS
249 Crop view on an axis (vertical,horizontal).
250 --padding FLOAT
252 Camera view padding.
253 --multi-sampling
255 Enable multi-sampling.
256 --no-vsync
258 Disable vsync.
259 --bloom-multiplier FLOAT
261 Adjust the amount of bloom.
262 --bloom-intensity FLOAT
264 Adjust the intensity of the bloom.
265 --max-files NUMBER
267 Set the maximum number of files or 0 for no limit. Excess files
268 will be discarded.
269 --max-file-lag SECONDS
271 Max time files of a commit can take to appear. Use -1 for no
272 limit.
273 --max-user-speed UNITS
275 Max speed users can travel per second.
276 --user-friction SECONDS
278 Time users take to come to a halt.
279 --user-scale SCALE
281 Change scale of user avatars.
282 --camera-mode MODE
284 Camera mode (overview,track).
285 --disable-auto-rotate
287 Disable automatic camera rotation.
288 --disable-input
290 Disable keyboard and mouse input.
291 --hide DISPLAY_ELEMENT
293 Hide one or more display elements from the list below:
294 bloom - bloom effect
296 date - current date
297 dirnames - names of directories
298 files - file icons
299 filenames - names of files
300 mouse - mouse cursor
301 progress - progress bar widget
302 root - root directory of the tree
303 tree - animated tree structure
304 users - user avatars
305 usernames - names of users
306 Separate multiple elements with commas (eg "mouse,progress")
308 --hash-seed SEED
311 Change the seed of hash function.
312 --caption-file FILE
314 Caption file (see Caption Log Format).
315 --caption-size SIZE
317 Caption size.
318 --caption-colour FFFFFF
320 Caption colour in hex.
321 --caption-duration SECONDS
323 Caption duration.
324 --caption-offset X
326 Caption horizontal offset (0 to centre captions).
327 -o, --output-ppm-stream FILE
329 Output a PPM image stream to a file ('-' for STDOUT).
330 This will automatically hide the progress bar initially and en‐
332 able 'stop-at-end' unless other behaviour is specified.
333 -r, --output-framerate FPS
336 Framerate of output (25,30,60). Used with --output-ppm-stream.
337 --output-custom-log FILE
339 Output a custom format log file ('-' for STDOUT).
340 --load-config CONFIG_FILE
342 Load a config file.
343 --save-config CONFIG_FILE
345 Save a config file with the current options.
346 --path PATH
348 path Either a supported version control directory, a pre-generated
350 log file (see log commands or the custom log format), a Gource
351 conf file or '-' to read STDIN.
352 If path is omitted, gource will attempt to read a log from the
354 current directory.
355 Git, Bazaar, Mercurial and SVN Examples
358 View the log of the repository in the current path:
359 gource
361 View the log of a project in the specified directory:
363 gource my-project-dir
365 For large projects, generating a log of the project history may take a
367 long time. For centralized VCS like SVN, generating the log will put
368 load on the central VCS server.
369 In these cases, you may like to save a copy of the log for later use.
371 You can generate a log in the VCS specific log format using the
373 --log-command VCS option:
374 cd my-svn-project
376 `gource --log-command svn` > my-svn-project.log
377 gource my-svn-project.log
378 You can also have Gource write a copy of the log file in its own for‐
380 mat:
381 gource --output-custom-log my-project-custom.log
383 CVS Support
386 Use 'cvs2cl' to generate the log and then pass it to Gource:
387 cvs2cl --chrono --stdout --xml -g-q > my-cvs-project.log
389 gource my-cvs-project.log
390 Custom Log Format
393 If you want to use Gource with something other than the supported sys‐
394 tems, there is a pipe ('|') delimited custom log format:
395 timestamp - An ISO 8601 or unix timestamp of when the update oc‐
397 curred.
398 username - The name of the user who made the update.
399 type - Single character for the update type - (A)dded, (M)odi‐
400 fied or (D)eleted.
401 file - Path of the file updated.
402 colour - A colour for the file in hex (FFFFFF) format. Optional.
403 Caption Log Format
406 Gource can display captions along the timeline by specifying a caption
407 file (using --caption-file) in the pipe ('|') delimited format below:
408 timestamp - An ISO 8601 or unix timestamp of when to display the
410 caption.
411 caption - The caption
412 Recording Videos
415 See the guide on the homepage for examples of recording videos with
416 Gource:
417 https://github.com/acaudwell/Gource/wiki/Videos
419 More Information
422 Visit the Gource homepage for guides and examples of using Gource with
423 various version control systems:
424 http://gource.io
426
429 The time shown in the top left of the screen is set initially from the
430 first log entry read and is incremented according to the simulation
431 speed (--seconds-per-day).
432 Pressing SPACE at any time will pause/resume the simulation. While
434 paused you may use the mouse to inspect the detail of individual files
435 and users.
436 TAB cycles through selecting the current visible users.
438 The camera mode, either tracking activity or showing the entire code
440 tree, can be toggled using the Middle mouse button.
441 You can drag the left mouse button to manually control the camera. The
443 right mouse button rotates the view.
444 Interactive keyboard commands:
446 (V) Toggle camera mode
448 (C) Displays Gource logo
449 (K) Toggle file extension key
450 (M) Toggle mouse visibility
451 (N) Jump forward in time to next log entry
452 (S) Randomize colours
453 (D) Toggle directory name display mode
454 (F) Toggle file name display mode
455 (U) Toggle user name display mode
456 (G) Toggle display of users
457 (T) Toggle display of directory tree edges
458 (R) Toggle display of root directory edges
459 (+-) Adjust simulation speed
460 (<>) Adjust time scale
461 (TAB) Cycle through visible users
462 (F12) Screenshot
463 (Alt+Enter) Fullscreen toggle
464 (ESC) Quit
465
467 Written by Andrew Caudwell
468 Project Homepage: http://gource.io
470
472 Copyright (C) 2009 Andrew Caudwell (acaudwell@gmail.com)
473 This program is free software; you can redistribute it and/or
475 modify it under the terms of the GNU General Public License
476 as published by the Free Software Foundation; either version
477 3 of the License, or (at your option) any later version.
478 This program is distributed in the hope that it will be useful,
480 but WITHOUT ANY WARRANTY; without even the implied warranty of
481 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
482 GNU General Public License for more details.
483 You should have received a copy of the GNU General Public License
485 along with this program. If not, see <http://www.gnu.org/licenses/>.
486
488 Catalyst IT (catalyst.net.nz)
489 For supporting the development of Gource!
491 Gource(1)