1Gource(1)                   General Commands Manual                  Gource(1)
2
3
4

NAME

6       Gource - a software version control visualization
7

SYNOPSIS

9       gource [options] [path]
10

DESCRIPTION

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

REQUIREMENTS

21       gource requires a OpenGL capable video card to run.
22

OPTIONS

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       --window-position XxY
38               Initial window position on your desktop which may be made up of
39               multiple monitors.
40
41               This will override the screen setting so don't specify both.
42
43       --frameless
44               Frameless window.
45
46       --transparent
47               Make the background transparent. Only really useful for screen‐
48               shots.
49
50       --start-date "YYYY-MM-DD hh:mm:ss +tz"
51               Start with the first entry after the supplied date and optional
52               time.
53
54               If a time zone offset isn't specified the local  time  zone  is
55               used.
56
57               Example accepted formats:
58
59                   "2012-06-30"
60                   "2012-06-30 12:00"
61                   "2012-06-30 12:00:00 +12"
62
63       --stop-date "YYYY-MM-DD hh:mm:ss +tz"
64               Stop  at the last entry prior to the supplied date and optional
65               time.
66
67               Uses the same format as --start-date.
68
69       -p, --start-position POSITION
70               Begin at some position in the log (between 0.0 and 1.0 or 'ran‐
71               dom').
72
73       --stop-position  POSITION
74               Stop  (exit)  at  some  position in the log (does not work with
75               STDIN).
76
77       -t, --stop-at-time SECONDS
78               Stop (exit) after a specified number of seconds.
79
80       --stop-at-end
81               Stop (exit) at the end of the log / stream.
82
83       --loop  Loop back to the start of the log when the end is reached.
84
85       --loop-delay-seconds SECONDS
86               Seconds to delay before looping.
87
88       -a, --auto-skip-seconds SECONDS
89               Automatically skip to next entry if nothing happens for a spec‐
90               ified number of seconds.
91
92       -s, --seconds-per-day SECONDS
93               Speed of simulation in seconds per day.
94
95       --realtime
96               Realtime playback speed.
97
98       --no-time-travel
99               Use  the  time of the last commit if the time of a commit is in
100               the past.
101
102       -c, --time-scale SCALE
103               Change simulation time scale.
104
105       -i, --file-idle-time SECONDS
106               Time in seconds files remain idle before they are removed or  0
107               for no limit.
108
109       -e, --elasticity FLOAT
110               Elasticity of nodes.
111
112       -b, --background-colour FFFFFF
113               Background colour in hex.
114
115       --background-image IMAGE
116               Set a background image.
117
118       --title TITLE
119               Set a title
120
121       --font-file FILE
122               Specify  the font. Should work with most font file formats sup‐
123               ported by FreeType, such as TTF and OTF, among others.
124
125       --font-scale SCALE
126               Scale the size of all fonts.
127
128       --font-size SIZE
129               Font size used by the date and title.
130
131       --file-font-size SIZE
132               Font size of filenames.
133
134       --dir-font-size SIZE
135               Font size of directory names.
136
137       --user-font-size SIZE
138               Font size of user names.
139
140       --font-colour FFFFFF
141               Font colour used by the date and title in hex.
142
143       --key   Show file extension key.
144
145       --logo IMAGE
146               Logo to display in the foreground.
147
148       --logo-offset XxY
149               Offset position of the logo.
150
151       --date-format FORMAT
152               Specify display date string (strftime format).
153
154       --log-command VCS
155               Show the log command used by gource (git,svn,hg,bzr,cvs2cl).
156
157       --log-format VCS
158               Specify     format     of     the      log      being      read
159               (git,svn,hg,bzr,cvs2cl,custom).   Required  when  reading  from
160               STDIN.
161
162       --git-branch
163               Get the git log of a branch other than the current one.
164
165       --follow-user USER
166               Have the camera automatically follow a particular user.
167
168       --highlight-dirs
169               Highlight the names of all directories.
170
171       --highlight-user USER
172               Highlight the names of a particular user.
173
174       --highlight-users
175               Highlight the names of all users.
176
177       --highlight-colour FFFFFF
178               Font colour for highlighted users in hex.
179
180       --selection-colour FFFFFF
181               Font colour for selected users and files.
182
183       --filename-colour FFFFFF
184               Font colour for filenames.
185
186       --dir-colour FFFFFF
187               Font colour for directories.
188
189       --dir-name-depth DEPTH
190               Draw names of directories down to a specific depth in the tree.
191
192       --dir-name-position FLOAT
193               Position along edge of the directory name (between 0.1 and 1.0,
194               default is 0.5).
195
196       --filename-time SECONDS
197               Duration to keep filenames on screen (>= 2.0).
198
199       --file-extensions
200               Show filename extensions only.
201
202       --file-extension-fallback
203               Use filename as extension if the extension is missing or empty.
204
205       --file-filter REGEX
206               Filter  out  file  paths matching the specified regular expres‐
207               sion.
208
209       --file-show-filter REGEX
210               Show only file paths matching the specified regular expression.
211
212       --user-filter REGEX
213               Filter usernames matching the specified regular expression.
214
215       --user-show-filter REGEX
216               Show only usernames matching the specified regular expression.
217
218       --user-image-dir DIRECTORY
219               Directory containing .jpg or .png images  of  users  (eg  "Full
220               Name.png") to use as avatars.
221
222       --default-user-image IMAGE
223               Path of .jpg to use as the default user image.
224
225       --colour-images
226               Colourize user images.
227
228       --crop AXIS
229               Crop view on an axis (vertical,horizontal).
230
231       --padding FLOAT
232               Camera view padding.
233
234       --multi-sampling
235               Enable multi-sampling.
236
237       --no-vsync
238               Disable vsync.
239
240       --bloom-multiplier FLOAT
241               Adjust the amount of bloom.
242
243       --bloom-intensity FLOAT
244               Adjust the intensity of the bloom.
245
246       --max-files NUMBER
247               Set the maximum number of files or 0 for no limit. Excess files
248               will be discarded.
249
250       --max-file-lag SECONDS
251               Max time files of a commit can take to appear. Use  -1  for  no
252               limit.
253
254       --max-user-speed UNITS
255               Max speed users can travel per second.
256
257       --user-friction SECONDS
258               Time users take to come to a halt.
259
260       --user-scale SCALE
261               Change scale of user avatars.
262
263       --camera-mode MODE
264               Camera mode (overview,track).
265
266       --disable-auto-rotate
267               Disable automatic camera rotation.
268
269       --disable-input
270               Disable keyboard and mouse input.
271
272       --hide DISPLAY_ELEMENT
273               Hide one or more display elements from the list below:
274
275                   bloom     - bloom effect
276                   date      - current date
277                   dirnames  - names of directories
278                   files     - file icons
279                   filenames - names of files
280                   mouse     - mouse cursor
281                   progress  - progress bar widget
282                   root      - root directory of the tree
283                   tree      - animated tree structure
284                   users     - user avatars
285                   usernames - names of users
286
287               Separate multiple elements with commas (eg "mouse,progress")
288
289
290       --hash-seed SEED
291               Change the seed of hash function.
292
293       --caption-file FILE
294               Caption file (see Caption Log Format).
295
296       --caption-size SIZE
297               Caption size.
298
299       --caption-colour FFFFFF
300               Caption colour in hex.
301
302       --caption-duration SECONDS
303               Caption duration.
304
305       --caption-offset X
306               Caption horizontal offset (0 to centre captions).
307
308       -o, --output-ppm-stream FILE
309               Output a PPM image stream to a file ('-' for STDOUT).
310
311               This  will  automatically  hide  the progress bar initially and
312               enable 'stop-at-end' unless other behaviour is specified.
313
314
315       -r, --output-framerate FPS
316               Framerate of output (25,30,60). Used with --output-ppm-stream.
317
318       --output-custom-log FILE
319               Output a custom format log file ('-' for STDOUT).
320
321       --load-config CONFIG_FILE
322               Load a config file.
323
324       --save-config CONFIG_FILE
325               Save a config file with the current options.
326
327       --path PATH
328
329       path    Either a supported version control directory,  a  pre-generated
330               log  file (see log commands or the custom log format), a Gource
331               conf file or '-' to read STDIN.
332
333               If path is omitted, gource will attempt to read a log from  the
334               current directory.
335
336
337   Git, Bazaar, Mercurial and SVN Examples
338       View the log of the repository in the current path:
339
340          gource
341
342       View the log of a project in the specified directory:
343
344          gource my-project-dir
345
346       For  large projects, generating a log of the project history may take a
347       long time. For centralized VCS like SVN, generating the  log  will  put
348       load on the central VCS server.
349
350       In these cases, you may like to save a copy of the log for later use.
351
352       You  can  generate  a  log  in  the  VCS  specific log format using the
353       --log-command VCS option:
354
355          cd my-svn-project
356          `gource --log-command svn` > my-svn-project.log
357          gource my-svn-project.log
358
359       You can also have Gource write a copy of the log file in its  own  for‐
360       mat:
361
362          gource --output-custom-log my-project-custom.log
363
364
365   CVS Support
366       Use 'cvs2cl' to generate the log and then pass it to Gource:
367
368          cvs2cl --chrono --stdout --xml -g-q > my-cvs-project.log
369          gource my-cvs-project.log
370
371
372   Custom Log Format
373       If  you want to use Gource with something other than the supported sys‐
374       tems, there is a pipe ('|') delimited custom log format:
375
376          timestamp - A unix timestamp of when the update occurred.
377          username  - The name of the user who made the update.
378          type      - Single character for the update type - (A)dded,  (M)odi‐
379       fied or (D)eleted.
380          file      - Path of the file updated.
381          colour    - A colour for the file in hex (FFFFFF) format. Optional.
382
383
384   Caption Log Format
385       Gource  can display captions along the timeline by specifying a caption
386       file (using --caption-file) in the pipe ('|') delimited format below:
387
388          timestamp - A unix timestamp of when to display the caption.
389          caption   - The caption
390
391
392   Recording Videos
393       See the guide on the homepage for examples  of  recording  videos  with
394       Gource:
395
396          https://github.com/acaudwell/Gource/wiki/Videos
397
398
399   More Information
400       Visit  the Gource homepage for guides and examples of using Gource with
401       various version control systems:
402
403          http://gource.io
404
405

INTERFACE

407       The time shown in the top left of the screen is set initially from  the
408       first  log  entry  read  and is incremented according to the simulation
409       speed (--seconds-per-day).
410
411       Pressing SPACE at any time  will  pause/resume  the  simulation.  While
412       paused  you may use the mouse to inspect the detail of individual files
413       and users.
414
415       TAB cycles through selecting the current visible users.
416
417       The camera mode, either tracking activity or showing  the  entire  code
418       tree, can be toggled using the Middle mouse button.
419
420       You  can drag the left mouse button to manually control the camera. The
421       right mouse button rotates the view.
422
423       Interactive keyboard commands:
424
425          (V)   Toggle camera mode
426          (C)   Displays Gource logo
427          (K)   Toggle file extension key
428          (M)   Toggle mouse visibility
429          (N)   Jump forward in time to next log entry
430          (S)   Randomize colours
431          (D)   Toggle directory name display mode
432          (F)   Toggle file name display mode
433          (U)   Toggle user name display mode
434          (G)   Toggle display of users
435          (T)   Toggle display of directory tree edges
436          (R)   Toggle display of root directory edges
437          (+-)  Adjust simulation speed
438          (<>)  Adjust time scale
439          (TAB) Cycle through visible users
440          (F12) Screenshot
441          (Alt+Enter) Fullscreen toggle
442          (ESC) Quit
443

AUTHOR

445        Written by Andrew Caudwell
446
447        Project Homepage: http://gource.io
448
450        Copyright (C) 2009 Andrew Caudwell (acaudwell@gmail.com)
451
452        This program is free software; you can redistribute it and/or
453        modify it under the terms of the GNU General Public License
454        as published by the Free Software Foundation; either version
455        3 of the License, or (at your option) any later version.
456
457        This program is distributed in the hope that it will be useful,
458        but WITHOUT ANY WARRANTY; without even the implied warranty of
459        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
460        GNU General Public License for more details.
461
462        You should have received a copy of the GNU General Public License
463        along with this program.  If not, see <http://www.gnu.org/licenses/>.
464

ACKNOWLEDGEMENTS

466        Catalyst IT (catalyst.net.nz)
467
468        For supporting the development of Gource!
469
470
471
472                                                                     Gource(1)
Impressum