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

INTERFACE

371       The  time shown in the top left of the screen is set initially from the
372       first log entry read and is incremented  according  to  the  simulation
373       speed (--seconds-per-day).
374
375       Pressing  SPACE  at  any  time  will pause/resume the simulation. While
376       paused you may use the mouse to inspect the detail of individual  files
377       and users.
378
379       TAB cycles through selecting the current visible users.
380
381       The  camera  mode,  either tracking activity or showing the entire code
382       tree, can be toggled using the Middle mouse button.
383
384       You can drag the left mouse button to manually control the camera.  The
385       right mouse button rotates the view.
386
387       Interactive keyboard commands:
388
389          (V)   Toggle camera mode
390          (C)   Displays Gource logo
391          (K)   Toggle file extension key
392          (M)   Toggle mouse visibility
393          (N)   Jump forward in time to next log entry
394          (S)   Randomize colours
395          (D)   Toggle directory name display mode
396          (F)   Toggle file name display mode
397          (U)   Toggle user name display mode
398          (G)   Toggle display of users
399          (T)   Toggle display of directory tree edges
400          (R)   Toggle display of root directory edges
401          (+-)  Adjust simulation speed
402          (<>)  Adjust time scale
403          (TAB) Cycle through visible users
404          (F12) Screenshot
405          (Alt+Enter) Fullscreen toggle
406          (ESC) Quit
407

AUTHOR

409        Written by Andrew Caudwell
410
411        Project Homepage: http://gource.io
412
414        Copyright (C) 2009 Andrew Caudwell (acaudwell@gmail.com)
415
416        This program is free software; you can redistribute it and/or
417        modify it under the terms of the GNU General Public License
418        as published by the Free Software Foundation; either version
419        3 of the License, or (at your option) any later version.
420
421        This program is distributed in the hope that it will be useful,
422        but WITHOUT ANY WARRANTY; without even the implied warranty of
423        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
424        GNU General Public License for more details.
425
426        You should have received a copy of the GNU General Public License
427        along with this program.  If not, see <http://www.gnu.org/licenses/>.
428

ACKNOWLEDGEMENTS

430        Catalyst IT (catalyst.net.nz)
431
432        For supporting the development of Gource!
433
434
435
436                                                                     Gource(1)
Impressum