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 --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
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
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
430 Catalyst IT (catalyst.net.nz)
431
432 For supporting the development of Gource!
433
434
435
436 Gource(1)