1
2 Gource
3
4 software version control visualization
5
6 Copyright (C) 2009 Andrew Caudwell
7
8 http://gource.io
9
10Contents
11========
12
131. Description
142. Requirements
153. Using Gource
164. Copyright
17
181. Description
19==============
20
21OpenGL-based 3D visualisation tool for source control repositories.
22
23The repository is displayed as a tree where the root of the repository is the
24centre, directories are branches and files are leaves. Contributors to the
25source code appear and disappear as they contribute to specific files and
26directories.
27
282. Requirements
29===============
30
31Gource's display is rendered using OpenGL and requires a 3D accelerated video
32card to run.
33
343. Using Gource
35===============
36
37gource [options] [path]
38
39options:
40
41 -h, --help
42 Help ('-H' for extended help).
43
44 -WIDTHxHEIGHT, --viewport WIDTHxHEIGHT
45 Set the viewport size. If -f is also supplied, will attempt to set
46 the video mode to this also. Add ! to make the window non-resizable.
47
48 --screen SCREEN
49 Set the number of the screen to display on.
50
51 --window-position XxY
52 Initial window position on your desktop which may be made up of
53 multiple monitors.
54
55 This will override the screen setting so don't specify both.
56
57 --frameless
58 Frameless window.
59
60 -f, --fullscreen
61 Fullscreen.
62
63 -w, --windowed
64 Windowed.
65
66 --transparent
67 Make the background transparent. Only really useful for screenshots.
68
69 --start-date "YYYY-MM-DD hh:mm:ss +tz"
70 Start with the first entry after the supplied date and optional time.
71
72 If a time zone offset isn't specified the local time zone is used.
73
74 Example accepted formats:
75
76 "2012-06-30"
77 "2012-06-30 12:00"
78 "2012-06-30 12:00:00 +12"
79
80 --stop-date "YYYY-MM-DD hh:mm:ss +tz"
81 Stop after the last entry prior to the supplied date and optional time.
82
83 Uses the same format as --start-date.
84
85 -p, --start-position POSITION
86 Begin at some position in the log (between 0.0 and 1.0 or 'random').
87
88 --stop-position POSITION
89 Stop (exit) at some position in the log (does not work with STDIN).
90
91 -t, --stop-at-time SECONDS
92 Stop (exit) after a specified number of seconds.
93
94 --stop-at-end
95 Stop (exit) at the end of the log / stream.
96
97 --loop
98 Loop back to the start of the log when the end is reached.
99
100 --loop-delay-seconds
101 Seconds to delay before looping.
102
103 -a, --auto-skip-seconds SECONDS
104 Skip to next entry if nothing happens for a number of seconds.
105
106 -s, --seconds-per-day SECONDS
107 Speed of simulation in seconds per day.
108
109 --realtime
110 Realtime playback speed.
111
112 --no-time-travel
113 Use the time of the last commit if the time of a commit is in the past.
114
115 -c, --time-scale SCALE
116 Change simulation time scale.
117
118 -i, --file-idle-time SECONDS
119 Time in seconds files remain idle before they are removed or 0
120 for no limit.
121
122 -e, --elasticity FLOAT
123 Elasticity of nodes.
124
125 -b, --background-colour FFFFFF
126 Background colour in hex.
127
128 --background-image IMAGE
129 Set a background image.
130
131 --logo IMAGE
132 Logo to display in the foreground.
133
134 --logo-offset XxY
135 Offset position of the logo.
136
137 --title TITLE
138 Set a title.
139
140 --font-file FILE
141 Specify the font. Should work with most font file formats supported by FreeType, such as TTF and OTF, among others.
142
143 --font-scale SCALE
144 Scale the size of all fonts.
145
146 --font-size SIZE
147 Font size used by the date and title.
148
149 --file-font-size SIZE
150 Font size of filenames.
151
152 --dir-font-size SIZE
153 Font size of directory names
154
155 --user-font-size SIZE
156 Font size of user names.
157
158 --font-colour FFFFFF
159 Font colour used by the date and title in hex.
160
161 --key
162 Show file extension key.
163
164 --date-format FORMAT
165 Specify display date string (strftime format).
166
167 --log-command VCS
168 Show the VCS log command used by gource (git,svn,hg,bzr,cvs2cl).
169
170 --log-format VCS
171 Specify the log format (git,svn,hg,bzr,cvs2cl,custom).
172
173 Required when reading from STDIN.
174
175 --git-branch
176 Get the git log of a branch other than the current one.
177
178 --follow-user USER
179 Have the camera automatically follow a particular user.
180
181 --highlight-dirs
182 Highlight the names of all directories.
183
184 --highlight-user USER
185 Highlight the names of a particular user.
186
187 --highlight-users
188 Highlight the names of all users.
189
190 --highlight-colour FFFFFF
191 Font colour for highlighted users in hex.
192
193 --selection-colour FFFFFF
194 Font colour for selected users and files.
195
196 --filename-colour FFFFFF
197 Font colour for filenames.
198
199 --dir-colour FFFFFF
200 Font colour for directories.
201
202 --dir-name-depth DEPTH
203 Draw names of directories down to a specific depth in the tree.
204
205 --dir-name-position FLOAT
206 Position along edge of the directory name
207 (between 0.1 and 1.0, default is 0.5).
208
209 --filename-time SECONDS
210 Duration to keep filenames on screen (>= 2.0).
211
212 --file-extensions
213 Show filename extensions only.
214
215 --file-extension-fallback
216 Use filename as extension if the extension is missing or empty.
217
218 --file-filter REGEX
219 Filter out file paths matching the specified regular expression.
220
221 --file-show-filter REGEX
222 Show only file paths matching the specified regular expression.
223
224 --user-filter REGEX
225 Filter usernames matching the specified regular expression.
226
227 --user-show-filter REGEX
228 Show only usernames matching the specified regular expression.
229
230 --user-image-dir DIRECTORY
231 Directory containing .jpg or .png images of users
232 (eg "Full Name.png") to use as avatars.
233
234 --default-user-image IMAGE
235 Path of .jpg or .png to use as the default user image.
236
237 --colour-images
238 Colourize user images.
239
240 --crop AXIS
241 Crop view on an axis (vertical,horizontal).
242
243 --padding FLOAT
244 Camera view padding.
245
246 --multi-sampling
247 Enable multi-sampling.
248
249 --no-vsync
250 Disable vsync.
251
252 --bloom-multiplier FLOAT
253 Adjust the amount of bloom.
254
255 --bloom-intensity FLOAT
256 Adjust the intensity of the bloom.
257
258 --max-files NUMBER
259 Set the maximum number of files or 0 for no limit.
260
261 Excess files will be discarded.
262
263 --max-file-lag SECONDS
264 Max time files of a commit can take to appear.
265
266 Use -1 for no limit.
267
268 --max-user-speed UNITS
269 Max speed users can travel per second.
270
271 --user-friction SECONDS
272 Time users take to come to a halt.
273
274 --user-scale SCALE
275 Change scale of user avatars.
276
277 --camera-mode MODE
278 Camera mode (overview,track).
279
280 --disable-auto-rotate
281 Disable automatic camera rotation.
282
283 --disable-input
284 Disable keyboard and mouse input.
285
286 --hide DISPLAY_ELEMENT
287 Hide one or more display elements from the list below:
288
289 bloom - bloom effect
290 date - current date
291 dirnames - names of directories
292 files - file icons
293 filenames - names of files
294 mouse - mouse cursor
295 progress - progress bar widget
296 root - root directory of tree
297 tree - animated tree structure
298 users - user avatars
299 usernames - names of users
300
301 Separate multiple elements with commas (eg "mouse,progress")
302
303 --hash-seed SEED
304 Change the seed of hash function.
305
306 --caption-file FILE
307 Caption file (see Caption Log Format).
308
309 --caption-size SIZE
310 Caption size.
311
312 --caption-colour FFFFFF
313 Caption colour in hex.
314
315 --caption-duration SECONDS
316 Caption duration.
317
318 --caption-offset X
319 Caption horizontal offset (0 to centre captions).
320
321 -o, --output-ppm-stream FILE
322 Output a PPM image stream to a file ('-' for STDOUT).
323
324 This will automatically hide the progress bar initially and
325 enable 'stop-at-end' unless other behaviour is specified.
326
327 -r, --output-framerate FPS
328 Framerate of output (25,30,60). Used with --output-ppm-stream.
329
330 --output-custom-log FILE
331 Output a custom format log file ('-' for STDOUT).
332
333 --load-config CONFIG_FILE
334 Load a gource conf file.
335
336 --save-config CONFIG_FILE
337 Save a gource conf file with the current options.
338
339 --path PATH
340
341 path Either a supported version control directory, a pre-generated log
342 file (see log commands or the custom log format), a Gource conf
343 file or '-' to read STDIN.
344
345 If path is omitted, gource will attempt to read a log from the
346 current directory.
347
348Git, Bazaar, Mercurial and SVN Examples:
349
350View the log of the repository in the current path:
351
352 gource
353
354View the log of a project in the specified directory:
355
356 gource my-project-dir
357
358For large projects, generating a log of the project history may take a long
359time. For centralized VCS like SVN, generating the log may also put load on
360the central VCS server.
361
362In these cases, you may like to save a copy of the log for later use.
363
364You can generate a log in the VCS specific log format using
365the --log-command VCS option:
366
367 cd my-svn-project
368 `gource --log-command svn` > my-svn-project.log
369 gource my-svn-project.log
370
371You can also have Gource write a copy of the log file in its own format:
372
373 gource --output-custom-log my-project-custom.log
374
375CVS Support:
376
377Use 'cvs2cl' to generate the log and then pass it to Gource:
378
379 cvs2cl --chrono --stdout --xml -g-q > my-cvs-project.log
380 gource my-cvs-project.log
381
382Custom Log Format:
383
384If you want to use Gource with something other than the supported systems,
385there is a pipe ('|') delimited custom log format:
386
387 timestamp - A unix timestamp of when the update occured.
388 username - The name of the user who made the update.
389 type - initial for the update type - (A)dded, (M)odified or (D)eleted.
390 file - Path of the file updated.
391 colour - A colour for the file in hex (FFFFFF) format. Optional.
392
393Caption Log Format:
394
395Gource can display captions along the timeline by specifying a caption file
396(using --caption-file) in the pipe ('|') delimited format below:
397
398 timestamp - A unix timestamp of when to display the caption.
399 caption - The caption
400
401Recording Videos:
402
403See the guide on the homepage for examples of recording videos with Gource:
404
405 https://github.com/acaudwell/Gource/wiki/Videos
406
407More Information:
408
409Visit the Gource homepage for guides and examples of using Gource with various
410version control systems:
411
412 http://gource.io
413
414Interface:
415
416The time shown in the top left of the screen is set initially from the first
417log entry read and is incremented according to the simulation speed
418(--seconds-per-day).
419
420Pressing SPACE at any time will pause/resume the simulation. While paused you
421may use the mouse to inspect the detail of individual files and users.
422
423TAB cycles through selecting the current visible users.
424
425The camera mode, either tracking activity or showing the entire code tree, can
426be toggled using the Middle mouse button.
427
428You can drag the left mouse button to manually control the camera. The right
429mouse button rotates the view.
430
431Interactive keyboard commands:
432
433 (V) Toggle camera mode
434 (C) Displays Gource logo
435 (K) Toggle file extension key
436 (M) Toggle mouse visibility
437 (N) Jump forward in time to next log entry
438 (S) Randomize colours
439 (D) Toggle directory name display mode
440 (F) Toggle file name display mode
441 (U) Toggle user name display mode
442 (G) Toggle display of users
443 (T) Toggle display of directory tree edges
444 (R) Toggle display of root directory edges
445 (+-) Adjust simulation speed
446 (<>) Adjust time scale
447 (TAB) Cycle through visible users
448 (F12) Screenshot
449 (Alt+Enter) Fullscreen toggle
450 (ESC) Quit
451
4524. Copyright
453============
454
455Gource - software version control visualization
456Copyright (C) 2009 Andrew Caudwell <acaudwell@gmail.com>
457
458This program is free software: you can redistribute it and/or modify
459it under the terms of the GNU General Public License as published by
460the Free Software Foundation, either version 3 of the License, or
461(at your option) any later version.
462
463This program is distributed in the hope that it will be useful,
464but WITHOUT ANY WARRANTY; without even the implied warranty of
465MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
466GNU General Public License for more details.
467
468You should have received a copy of the GNU General Public License
469along with this program. If not, see <http://www.gnu.org/licenses/>.
470
