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 --window-position XxY
38 Initial window position on your desktop which may be made up of
39 multiple monitors.
40 This will override the screen setting so don't specify both.
42 --frameless
44 Frameless window.
45 --transparent
47 Make the background transparent. Only really useful for screen‐
48 shots.
49 --start-date "YYYY-MM-DD hh:mm:ss +tz"
51 Start with the first entry after the supplied date and optional
52 time.
53 If a time zone offset isn't specified the local time zone is
55 used.
56 Example accepted formats:
58 "2012-06-30"
60 "2012-06-30 12:00"
61 "2012-06-30 12:00:00 +12"
62 --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 Uses the same format as --start-date.
68 -p, --start-position POSITION
70 Begin at some position in the log (between 0.0 and 1.0 or 'ran‐
71 dom').
72 --stop-position POSITION
74 Stop (exit) at some position in the log (does not work with
75 STDIN).
76 -t, --stop-at-time SECONDS
78 Stop (exit) after a specified number of seconds.
79 --stop-at-end
81 Stop (exit) at the end of the log / stream.
82 --loop Loop back to the start of the log when the end is reached.
84 --loop-delay-seconds SECONDS
86 Seconds to delay before looping.
87 -a, --auto-skip-seconds SECONDS
89 Automatically skip to next entry if nothing happens for a spec‐
90 ified number of seconds.
91 -s, --seconds-per-day SECONDS
93 Speed of simulation in seconds per day.
94 --realtime
96 Realtime playback speed.
97 --no-time-travel
99 Use the time of the last commit if the time of a commit is in
100 the past.
101 -c, --time-scale SCALE
103 Change simulation time scale.
104 -i, --file-idle-time SECONDS
106 Time in seconds files remain idle before they are removed or 0
107 for no limit.
108 -e, --elasticity FLOAT
110 Elasticity of nodes.
111 -b, --background-colour FFFFFF
113 Background colour in hex.
114 --background-image IMAGE
116 Set a background image.
117 --title TITLE
119 Set a title
120 --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 --font-scale SCALE
126 Scale the size of all fonts.
127 --font-size SIZE
129 Font size used by the date and title.
130 --file-font-size SIZE
132 Font size of filenames.
133 --dir-font-size SIZE
135 Font size of directory names.
136 --user-font-size SIZE
138 Font size of user names.
139 --font-colour FFFFFF
141 Font colour used by the date and title in hex.
142 --key Show file extension key.
144 --logo IMAGE
146 Logo to display in the foreground.
147 --logo-offset XxY
149 Offset position of the logo.
150 --date-format FORMAT
152 Specify display date string (strftime format).
153 --log-command VCS
155 Show the log command used by gource (git,svn,hg,bzr,cvs2cl).
156 --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 --git-branch
163 Get the git log of a branch other than the current one.
164 --follow-user USER
166 Have the camera automatically follow a particular user.
167 --highlight-dirs
169 Highlight the names of all directories.
170 --highlight-user USER
172 Highlight the names of a particular user.
173 --highlight-users
175 Highlight the names of all users.
176 --highlight-colour FFFFFF
178 Font colour for highlighted users in hex.
179 --selection-colour FFFFFF
181 Font colour for selected users and files.
182 --filename-colour FFFFFF
184 Font colour for filenames.
185 --dir-colour FFFFFF
187 Font colour for directories.
188 --dir-name-depth DEPTH
190 Draw names of directories down to a specific depth in the tree.
191 --dir-name-position FLOAT
193 Position along edge of the directory name (between 0.1 and 1.0,
194 default is 0.5).
195 --filename-time SECONDS
197 Duration to keep filenames on screen (>= 2.0).
198 --file-extensions
200 Show filename extensions only.
201 --file-extension-fallback
203 Use filename as extension if the extension is missing or empty.
204 --file-filter REGEX
206 Filter out file paths matching the specified regular expres‐
207 sion.
208 --file-show-filter REGEX
210 Show only file paths matching the specified regular expression.
211 --user-filter REGEX
213 Filter usernames matching the specified regular expression.
214 --user-show-filter REGEX
216 Show only usernames matching the specified regular expression.
217 --user-image-dir DIRECTORY
219 Directory containing .jpg or .png images of users (eg "Full
220 Name.png") to use as avatars.
221 --default-user-image IMAGE
223 Path of .jpg to use as the default user image.
224 --colour-images
226 Colourize user images.
227 --crop AXIS
229 Crop view on an axis (vertical,horizontal).
230 --padding FLOAT
232 Camera view padding.
233 --multi-sampling
235 Enable multi-sampling.
236 --no-vsync
238 Disable vsync.
239 --bloom-multiplier FLOAT
241 Adjust the amount of bloom.
242 --bloom-intensity FLOAT
244 Adjust the intensity of the bloom.
245 --max-files NUMBER
247 Set the maximum number of files or 0 for no limit. Excess files
248 will be discarded.
249 --max-file-lag SECONDS
251 Max time files of a commit can take to appear. Use -1 for no
252 limit.
253 --max-user-speed UNITS
255 Max speed users can travel per second.
256 --user-friction SECONDS
258 Time users take to come to a halt.
259 --user-scale SCALE
261 Change scale of user avatars.
262 --camera-mode MODE
264 Camera mode (overview,track).
265 --disable-auto-rotate
267 Disable automatic camera rotation.
268 --disable-input
270 Disable keyboard and mouse input.
271 --hide DISPLAY_ELEMENT
273 Hide one or more display elements from the list below:
274 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 Separate multiple elements with commas (eg "mouse,progress")
288 --hash-seed SEED
291 Change the seed of hash function.
292 --caption-file FILE
294 Caption file (see Caption Log Format).
295 --caption-size SIZE
297 Caption size.
298 --caption-colour FFFFFF
300 Caption colour in hex.
301 --caption-duration SECONDS
303 Caption duration.
304 --caption-offset X
306 Caption horizontal offset (0 to centre captions).
307 -o, --output-ppm-stream FILE
309 Output a PPM image stream to a file ('-' for STDOUT).
310 This will automatically hide the progress bar initially and
312 enable 'stop-at-end' unless other behaviour is specified.
313 -r, --output-framerate FPS
316 Framerate of output (25,30,60). Used with --output-ppm-stream.
317 --output-custom-log FILE
319 Output a custom format log file ('-' for STDOUT).
320 --load-config CONFIG_FILE
322 Load a config file.
323 --save-config CONFIG_FILE
325 Save a config file with the current options.
326 --path PATH
328 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 If path is omitted, gource will attempt to read a log from the
334 current directory.
335 Git, Bazaar, Mercurial and SVN Examples
338 View the log of the repository in the current path:
339 gource
341 View the log of a project in the specified directory:
343 gource my-project-dir
345 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 In these cases, you may like to save a copy of the log for later use.
351 You can generate a log in the VCS specific log format using the
353 --log-command VCS option:
354 cd my-svn-project
356 `gource --log-command svn` > my-svn-project.log
357 gource my-svn-project.log
358 You can also have Gource write a copy of the log file in its own for‐
360 mat:
361 gource --output-custom-log my-project-custom.log
363 CVS Support
366 Use 'cvs2cl' to generate the log and then pass it to Gource:
367 cvs2cl --chrono --stdout --xml -g-q > my-cvs-project.log
369 gource my-cvs-project.log
370 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 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 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 timestamp - A unix timestamp of when to display the caption.
389 caption - The caption
390 Recording Videos
393 See the guide on the homepage for examples of recording videos with
394 Gource:
395 https://github.com/acaudwell/Gource/wiki/Videos
397 More Information
400 Visit the Gource homepage for guides and examples of using Gource with
401 various version control systems:
402 http://gource.io
404
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 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 TAB cycles through selecting the current visible users.
416 The camera mode, either tracking activity or showing the entire code
418 tree, can be toggled using the Middle mouse button.
419 You can drag the left mouse button to manually control the camera. The
421 right mouse button rotates the view.
422 Interactive keyboard commands:
424 (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
445 Written by Andrew Caudwell
446 Project Homepage: http://gource.io
448
450 Copyright (C) 2009 Andrew Caudwell (acaudwell@gmail.com)
451 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 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 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
466 Catalyst IT (catalyst.net.nz)
467 For supporting the development of Gource!
469 Gource(1)