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 -i, --file-idle-time SECONDS
117 Time in seconds files remain idle before they are removed or 0
118 for no limit.
119 --file-idle-time-at-end SECONDS
121 Time in seconds files remain idle at the end before they are
122 removed.
123 -e, --elasticity FLOAT
125 Elasticity of nodes.
126 -b, --background-colour FFFFFF
128 Background colour in hex.
129 --background-image IMAGE
131 Set a background image.
132 --title TITLE
134 Set a title
135 --font-file FILE
137 Specify the font. Should work with most font file formats sup‐
138 ported by FreeType, such as TTF and OTF, among others.
139 --font-scale SCALE
141 Scale the size of all fonts.
142 --font-size SIZE
144 Font size used by the date and title.
145 --file-font-size SIZE
147 Font size of filenames.
148 --dir-font-size SIZE
150 Font size of directory names.
151 --user-font-size SIZE
153 Font size of user names.
154 --font-colour FFFFFF
156 Font colour used by the date and title in hex.
157 --key Show file extension key.
159 --logo IMAGE
161 Logo to display in the foreground.
162 --logo-offset XxY
164 Offset position of the logo.
165 --date-format FORMAT
167 Specify display date string (strftime format).
168 --log-command VCS
170 Show the log command used by gource (git,svn,hg,bzr,cvs2cl).
171 --log-format VCS
173 Specify format of the log being read
174 (git,svn,hg,bzr,cvs2cl,custom). Required when reading from
175 STDIN.
176 --git-branch
178 Get the git log of a branch other than the current one.
179 --follow-user USER
181 Have the camera automatically follow a particular user.
182 --highlight-dirs
184 Highlight the names of all directories.
185 --highlight-user USER
187 Highlight the names of a particular user.
188 --highlight-users
190 Highlight the names of all users.
191 --highlight-colour FFFFFF
193 Font colour for highlighted users in hex.
194 --selection-colour FFFFFF
196 Font colour for selected users and files.
197 --filename-colour FFFFFF
199 Font colour for filenames.
200 --dir-colour FFFFFF
202 Font colour for directories.
203 --dir-name-depth DEPTH
205 Draw names of directories down to a specific depth in the tree.
206 --dir-name-position FLOAT
208 Position along edge of the directory name (between 0.1 and 1.0,
209 default is 0.5).
210 --filename-time SECONDS
212 Duration to keep filenames on screen (>= 2.0).
213 --file-extensions
215 Show filename extensions only.
216 --file-extension-fallback
218 Use filename as extension if the extension is missing or empty.
219 --file-filter REGEX
221 Filter out file paths matching the specified regular expres‐
222 sion.
223 --file-show-filter REGEX
225 Show only file paths matching the specified regular expression.
226 --user-filter REGEX
228 Filter usernames matching the specified regular expression.
229 --user-show-filter REGEX
231 Show only usernames matching the specified regular expression.
232 --user-image-dir DIRECTORY
234 Directory containing .jpg or .png images of users (eg "Full
235 Name.png") to use as avatars.
236 --default-user-image IMAGE
238 Path of .jpg to use as the default user image.
239 --fixed-user-size
241 Forces the size of the user image to remain fixed throughout.
242 --colour-images
244 Colourize user images.
245 --crop AXIS
247 Crop view on an axis (vertical,horizontal).
248 --padding FLOAT
250 Camera view padding.
251 --multi-sampling
253 Enable multi-sampling.
254 --no-vsync
256 Disable vsync.
257 --bloom-multiplier FLOAT
259 Adjust the amount of bloom.
260 --bloom-intensity FLOAT
262 Adjust the intensity of the bloom.
263 --max-files NUMBER
265 Set the maximum number of files or 0 for no limit. Excess files
266 will be discarded.
267 --max-file-lag SECONDS
269 Max time files of a commit can take to appear. Use -1 for no
270 limit.
271 --max-user-speed UNITS
273 Max speed users can travel per second.
274 --user-friction SECONDS
276 Time users take to come to a halt.
277 --user-scale SCALE
279 Change scale of user avatars.
280 --camera-mode MODE
282 Camera mode (overview,track).
283 --disable-auto-rotate
285 Disable automatic camera rotation.
286 --disable-input
288 Disable keyboard and mouse input.
289 --hide DISPLAY_ELEMENT
291 Hide one or more display elements from the list below:
292 bloom - bloom effect
294 date - current date
295 dirnames - names of directories
296 files - file icons
297 filenames - names of files
298 mouse - mouse cursor
299 progress - progress bar widget
300 root - root directory of the tree
301 tree - animated tree structure
302 users - user avatars
303 usernames - names of users
304 Separate multiple elements with commas (eg "mouse,progress")
306 --hash-seed SEED
309 Change the seed of hash function.
310 --caption-file FILE
312 Caption file (see Caption Log Format).
313 --caption-size SIZE
315 Caption size.
316 --caption-colour FFFFFF
318 Caption colour in hex.
319 --caption-duration SECONDS
321 Caption duration.
322 --caption-offset X
324 Caption horizontal offset (0 to centre captions).
325 -o, --output-ppm-stream FILE
327 Output a PPM image stream to a file ('-' for STDOUT).
328 This will automatically hide the progress bar initially and en‐
330 able 'stop-at-end' unless other behaviour is specified.
331 -r, --output-framerate FPS
334 Framerate of output (25,30,60). Used with --output-ppm-stream.
335 --output-custom-log FILE
337 Output a custom format log file ('-' for STDOUT).
338 --load-config CONFIG_FILE
340 Load a config file.
341 --save-config CONFIG_FILE
343 Save a config file with the current options.
344 --path PATH
346 path Either a supported version control directory, a pre-generated
348 log file (see log commands or the custom log format), a Gource
349 conf file or '-' to read STDIN.
350 If path is omitted, gource will attempt to read a log from the
352 current directory.
353 Git, Bazaar, Mercurial and SVN Examples
356 View the log of the repository in the current path:
357 gource
359 View the log of a project in the specified directory:
361 gource my-project-dir
363 For large projects, generating a log of the project history may take a
365 long time. For centralized VCS like SVN, generating the log will put
366 load on the central VCS server.
367 In these cases, you may like to save a copy of the log for later use.
369 You can generate a log in the VCS specific log format using the
371 --log-command VCS option:
372 cd my-svn-project
374 `gource --log-command svn` > my-svn-project.log
375 gource my-svn-project.log
376 You can also have Gource write a copy of the log file in its own for‐
378 mat:
379 gource --output-custom-log my-project-custom.log
381 CVS Support
384 Use 'cvs2cl' to generate the log and then pass it to Gource:
385 cvs2cl --chrono --stdout --xml -g-q > my-cvs-project.log
387 gource my-cvs-project.log
388 Custom Log Format
391 If you want to use Gource with something other than the supported sys‐
392 tems, there is a pipe ('|') delimited custom log format:
393 timestamp - An ISO 8601 or unix timestamp of when the update oc‐
395 curred.
396 username - The name of the user who made the update.
397 type - Single character for the update type - (A)dded, (M)odi‐
398 fied or (D)eleted.
399 file - Path of the file updated.
400 colour - A colour for the file in hex (FFFFFF) format. Optional.
401 Caption Log Format
404 Gource can display captions along the timeline by specifying a caption
405 file (using --caption-file) in the pipe ('|') delimited format below:
406 timestamp - An ISO 8601 or unix timestamp of when to display the
408 caption.
409 caption - The caption
410 Recording Videos
413 See the guide on the homepage for examples of recording videos with
414 Gource:
415 https://github.com/acaudwell/Gource/wiki/Videos
417 More Information
420 Visit the Gource homepage for guides and examples of using Gource with
421 various version control systems:
422 http://gource.io
424
427 The time shown in the top left of the screen is set initially from the
428 first log entry read and is incremented according to the simulation
429 speed (--seconds-per-day).
430 Pressing SPACE at any time will pause/resume the simulation. While
432 paused you may use the mouse to inspect the detail of individual files
433 and users.
434 TAB cycles through selecting the current visible users.
436 The camera mode, either tracking activity or showing the entire code
438 tree, can be toggled using the Middle mouse button.
439 You can drag the left mouse button to manually control the camera. The
441 right mouse button rotates the view.
442 Interactive keyboard commands:
444 (V) Toggle camera mode
446 (C) Displays Gource logo
447 (K) Toggle file extension key
448 (M) Toggle mouse visibility
449 (N) Jump forward in time to next log entry
450 (S) Randomize colours
451 (D) Toggle directory name display mode
452 (F) Toggle file name display mode
453 (U) Toggle user name display mode
454 (G) Toggle display of users
455 (T) Toggle display of directory tree edges
456 (R) Toggle display of root directory edges
457 (+-) Adjust simulation speed
458 (<>) Adjust time scale
459 (TAB) Cycle through visible users
460 (F12) Screenshot
461 (Alt+Enter) Fullscreen toggle
462 (ESC) Quit
463
465 Written by Andrew Caudwell
466 Project Homepage: http://gource.io
468
470 Copyright (C) 2009 Andrew Caudwell (acaudwell@gmail.com)
471 This program is free software; you can redistribute it and/or
473 modify it under the terms of the GNU General Public License
474 as published by the Free Software Foundation; either version
475 3 of the License, or (at your option) any later version.
476 This program is distributed in the hope that it will be useful,
478 but WITHOUT ANY WARRANTY; without even the implied warranty of
479 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
480 GNU General Public License for more details.
481 You should have received a copy of the GNU General Public License
483 along with this program. If not, see <http://www.gnu.org/licenses/>.
484
486 Catalyst IT (catalyst.net.nz)
487 For supporting the development of Gource!
489 Gource(1)