1Gource(1) General Commands Manual Gource(1)
2
3
4
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
15 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
27 -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
32 -f Fullscreen.
33
34 --screen SCREEN
35 Set the number of the screen to display on.
36
37 --high-dpi
38 Request a high DPI display when creating the window.
39
40 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
44 E.g. requesting a high DPI 800x600 window may produce a window
45 that is 1600x1200 pixels.
46
47
48 --window-position XxY
49 Initial window position on your desktop which may be made up of
50 multiple monitors.
51
52 This will override the screen setting so don't specify both.
53
54 --frameless
55 Frameless window.
56
57 --transparent
58 Make the background transparent. Only really useful for screen‐
59 shots.
60
61 --start-date "YYYY-MM-DD hh:mm:ss +tz"
62 Start with the first entry after the supplied date and optional
63 time.
64
65 If a time zone offset isn't specified the local time zone is
66 used.
67
68 Example accepted formats:
69
70 "2012-06-30"
71 "2012-06-30 12:00"
72 "2012-06-30 12:00:00 +12"
73
74 --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
78 Uses the same format as --start-date.
79
80 -p, --start-position POSITION
81 Begin at some position in the log (between 0.0 and 1.0 or 'ran‐
82 dom').
83
84 --stop-position POSITION
85 Stop (exit) at some position in the log (does not work with
86 STDIN).
87
88 -t, --stop-at-time SECONDS
89 Stop (exit) after a specified number of seconds.
90
91 --stop-at-end
92 Stop (exit) at the end of the log / stream.
93
94 --loop Loop back to the start of the log when the end is reached.
95
96 --loop-delay-seconds SECONDS
97 Seconds to delay before looping.
98
99 -a, --auto-skip-seconds SECONDS
100 Automatically skip to next entry if nothing happens for a spec‐
101 ified number of seconds.
102
103 -s, --seconds-per-day SECONDS
104 Speed of simulation in seconds per day.
105
106 --realtime
107 Realtime playback speed.
108
109 --no-time-travel
110 Use the time of the last commit if the time of a commit is in
111 the past.
112
113 -c, --time-scale SCALE
114 Change simulation time scale.
115
116 -i, --file-idle-time SECONDS
117 Time in seconds files remain idle before they are removed or 0
118 for no limit.
119
120 --file-idle-time-at-end SECONDS
121 Time in seconds files remain idle at the end before they are
122 removed.
123
124 -e, --elasticity FLOAT
125 Elasticity of nodes.
126
127 -b, --background-colour FFFFFF
128 Background colour in hex.
129
130 --background-image IMAGE
131 Set a background image.
132
133 --title TITLE
134 Set a title
135
136 --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
140 --font-scale SCALE
141 Scale the size of all fonts.
142
143 --font-size SIZE
144 Font size used by the date and title.
145
146 --file-font-size SIZE
147 Font size of filenames.
148
149 --dir-font-size SIZE
150 Font size of directory names.
151
152 --user-font-size SIZE
153 Font size of user names.
154
155 --font-colour FFFFFF
156 Font colour used by the date and title in hex.
157
158 --key Show file extension key.
159
160 --logo IMAGE
161 Logo to display in the foreground.
162
163 --logo-offset XxY
164 Offset position of the logo.
165
166 --date-format FORMAT
167 Specify display date string (strftime format).
168
169 --log-command VCS
170 Show the log command used by gource (git,svn,hg,bzr,cvs2cl).
171
172 --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
177 --git-branch
178 Get the git log of a branch other than the current one.
179
180 --follow-user USER
181 Have the camera automatically follow a particular user.
182
183 --highlight-dirs
184 Highlight the names of all directories.
185
186 --highlight-user USER
187 Highlight the names of a particular user.
188
189 --highlight-users
190 Highlight the names of all users.
191
192 --highlight-colour FFFFFF
193 Font colour for highlighted users in hex.
194
195 --selection-colour FFFFFF
196 Font colour for selected users and files.
197
198 --filename-colour FFFFFF
199 Font colour for filenames.
200
201 --dir-colour FFFFFF
202 Font colour for directories.
203
204 --dir-name-depth DEPTH
205 Draw names of directories down to a specific depth in the tree.
206
207 --dir-name-position FLOAT
208 Position along edge of the directory name (between 0.1 and 1.0,
209 default is 0.5).
210
211 --filename-time SECONDS
212 Duration to keep filenames on screen (>= 2.0).
213
214 --file-extensions
215 Show filename extensions only.
216
217 --file-extension-fallback
218 Use filename as extension if the extension is missing or empty.
219
220 --file-filter REGEX
221 Filter out file paths matching the specified regular expres‐
222 sion.
223
224 --file-show-filter REGEX
225 Show only file paths matching the specified regular expression.
226
227 --user-filter REGEX
228 Filter usernames matching the specified regular expression.
229
230 --user-show-filter REGEX
231 Show only usernames matching the specified regular expression.
232
233 --user-image-dir DIRECTORY
234 Directory containing .jpg or .png images of users (eg "Full
235 Name.png") to use as avatars.
236
237 --default-user-image IMAGE
238 Path of .jpg to use as the default user image.
239
240 --fixed-user-size
241 Forces the size of the user image to remain fixed throughout.
242
243 --colour-images
244 Colourize user images.
245
246 --crop AXIS
247 Crop view on an axis (vertical,horizontal).
248
249 --padding FLOAT
250 Camera view padding.
251
252 --multi-sampling
253 Enable multi-sampling.
254
255 --no-vsync
256 Disable vsync.
257
258 --bloom-multiplier FLOAT
259 Adjust the amount of bloom.
260
261 --bloom-intensity FLOAT
262 Adjust the intensity of the bloom.
263
264 --max-files NUMBER
265 Set the maximum number of files or 0 for no limit. Excess files
266 will be discarded.
267
268 --max-file-lag SECONDS
269 Max time files of a commit can take to appear. Use -1 for no
270 limit.
271
272 --max-user-speed UNITS
273 Max speed users can travel per second.
274
275 --user-friction SECONDS
276 Time users take to come to a halt.
277
278 --user-scale SCALE
279 Change scale of user avatars.
280
281 --camera-mode MODE
282 Camera mode (overview,track).
283
284 --disable-auto-rotate
285 Disable automatic camera rotation.
286
287 --disable-input
288 Disable keyboard and mouse input.
289
290 --hide DISPLAY_ELEMENT
291 Hide one or more display elements from the list below:
292
293 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
305 Separate multiple elements with commas (eg "mouse,progress")
306
307
308 --hash-seed SEED
309 Change the seed of hash function.
310
311 --caption-file FILE
312 Caption file (see Caption Log Format).
313
314 --caption-size SIZE
315 Caption size.
316
317 --caption-colour FFFFFF
318 Caption colour in hex.
319
320 --caption-duration SECONDS
321 Caption duration.
322
323 --caption-offset X
324 Caption horizontal offset (0 to centre captions).
325
326 -o, --output-ppm-stream FILE
327 Output a PPM image stream to a file ('-' for STDOUT).
328
329 This will automatically hide the progress bar initially and en‐
330 able 'stop-at-end' unless other behaviour is specified.
331
332
333 -r, --output-framerate FPS
334 Framerate of output (25,30,60). Used with --output-ppm-stream.
335
336 --output-custom-log FILE
337 Output a custom format log file ('-' for STDOUT).
338
339 --load-config CONFIG_FILE
340 Load a config file.
341
342 --save-config CONFIG_FILE
343 Save a config file with the current options.
344
345 --path PATH
346
347 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
351 If path is omitted, gource will attempt to read a log from the
352 current directory.
353
354
355 Git, Bazaar, Mercurial and SVN Examples
356 View the log of the repository in the current path:
357
358 gource
359
360 View the log of a project in the specified directory:
361
362 gource my-project-dir
363
364 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
368 In these cases, you may like to save a copy of the log for later use.
369
370 You can generate a log in the VCS specific log format using the
371 --log-command VCS option:
372
373 cd my-svn-project
374 `gource --log-command svn` > my-svn-project.log
375 gource my-svn-project.log
376
377 You can also have Gource write a copy of the log file in its own for‐
378 mat:
379
380 gource --output-custom-log my-project-custom.log
381
382
383 CVS Support
384 Use 'cvs2cl' to generate the log and then pass it to Gource:
385
386 cvs2cl --chrono --stdout --xml -g-q > my-cvs-project.log
387 gource my-cvs-project.log
388
389
390 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
394 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
402
403 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
407 timestamp - An ISO 8601 or unix timestamp of when to display the
408 caption.
409 caption - The caption
410
411
412 Recording Videos
413 See the guide on the homepage for examples of recording videos with
414 Gource:
415
416 https://github.com/acaudwell/Gource/wiki/Videos
417
418
419 More Information
420 Visit the Gource homepage for guides and examples of using Gource with
421 various version control systems:
422
423 http://gource.io
424
425
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
431 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
435 TAB cycles through selecting the current visible users.
436
437 The camera mode, either tracking activity or showing the entire code
438 tree, can be toggled using the Middle mouse button.
439
440 You can drag the left mouse button to manually control the camera. The
441 right mouse button rotates the view.
442
443 Interactive keyboard commands:
444
445 (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
467 Project Homepage: http://gource.io
468
470 Copyright (C) 2009 Andrew Caudwell (acaudwell@gmail.com)
471
472 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
477 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
482 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
488 For supporting the development of Gource!
489
490
491
492 Gource(1)