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.
30 -f Fullscreen
32 -w Windowed
34 --transparent
36 Make the background transparent. Only really useful for screen‐
37 shots.
38 -p, --start-position POSITION
40 Begin at some position in the log (between 0.0 and 1.0 or 'ran‐
41 dom').
42 --stop-position POSITION
44 Stop (exit) at some position in the log (does not work with
45 STDIN).
46 -t, --stop-at-time SECONDS
48 Stop (exit) after a specified number of seconds.
49 --stop-at-end
51 Stop (exit) at the end of the log / stream.
52 --loop
54 Loop back to the start of the log when the end is reached.
55 -a, --auto-skip-seconds SECONDS
57 Automatically skip to next entry if nothing happens for a spec‐
58 ified number of seconds.
59 -s, --seconds-per-day SECONDS
61 Speed of simulation in seconds per day.
62 --realtime
64 Realtime playback speed.
65 -c, --time-scale SCALE
67 Change simulation time scale.
68 -i, --file-idle-time SECONDS
70 Time in seconds files remain idle before they are removed or 0
71 for no limit.
72 -e, --elasticity FLOAT
74 Elasticity of nodes.
75 -b, --background-colour FFFFFF
77 Background colour in hex.
78 --background-image IMAGE
80 Set a background image.
81 --title TITLE
83 Set a title
84 --font-size SIZE
86 Font size.
87 --font-colour FFFFFF
89 Font colour in hex.
90 --key Show file extension key.
92 --logo IMAGE
94 Logo to display in the foreground.
95 --logo-offset XxY
97 Offset position of the logo.
98 --date-format FORMAT
100 Specify display date string (strftime format).
101 --log-command VCS
103 Show the log command used by gource (git,svn,hg,bzr,cvs2cl).
104 --log-format VCS
106 Specify format of the log being read
107 (git,svn,hg,bzr,cvs2cl,custom). Required when reading from
108 STDIN.
109 --git-branch
111 Get the git log of a branch other than the current one.
112 --follow-user USER
114 Have the camera automatically follow a particular user.
115 --highlight-user USER
117 Highlight the names of a particular user.
118 --highlight-users
120 Highlight the names of all users.
121 --highlight-dirs
123 Highlight the names of all directories.
124 --highlight-colour FFFFFF
126 Highlighted text colour in hex.
127 --file-extensions
129 Show filename extensions only.
130 --file-filter REGEX
132 Filter out any files matching a specified regular expression.
133 --user-filter REGEX
135 Filter out any usernames matching a specified regular expres‐
136 sion.
137 --user-image-dir DIRECTORY
139 Directory containing .jpg or .png images of users (eg 'Full
140 Name.png') to use as avatars.
141 --default-user-image IMAGE
143 Path of .jpg to use as the default user image.
144 --colour-images
146 Colourize user images.
147 --crop AXIS
149 Crop view on an axis (vertical,horizontal).
150 --padding FLOAT
152 Camera view padding.
153 --multi-sampling
155 Enable multi-sampling.
156 --bloom-multiplier FLOAT
158 Adjust the amount of bloom.
159 --bloom-intensity FLOAT
161 Adjust the intensity of the bloom.
162 --max-files
164 Set the maximum number of files or 0 for no limit. Excess files
165 will be discarded.
166 --max-file-lag SECONDS
168 Max time files of a commit can take to appear. Use -1 for no
169 limit.
170 --max-user-speed UNITS
172 Max speed users can travel per second.
173 --user-friction SECONDS
175 Time users come to a complete hault.
176 --user-scale SCALE
178 Change scale of users.
179 --camera-mode MODE
181 Camera mode (overview,track).
182 --disable-auto-rotate
184 Disable automatic camera rotation.
185 --hide DISPLAY_ELEMENT
187 Hide one or more display elements from the list below:
188 bloom - bloom effect
190 date - current date
191 dirnames - names of directories
192 files - file icons
193 filenames - names of files
194 mouse - mouse cursor
195 progress - progress bar widget
196 tree - animated tree structure
197 users - user avatars
198 usernames - names of users
199 Separate multiple elements with commas (eg 'mouse,progress')
201 --hash-seed SEED
204 Change the seed of hash function.
205 -o, --output-ppm-stream FILE
207 Output a PPM image stream to a file ('-' for STDOUT).
208 This will automatically hide the progress bar initially and
210 enable 'stop-at-end' unless other behaviour is specified.
211 -r, --output-framerate FPS
214 Framerate of output (25,30,60). Used with --output-ppm-stream.
215 --output-custom-log FILE
217 Output a custom format log file ('-' for STDOUT).
218 --load-config CONFIG_FILE
220 Load a config file.
221 --save-config CONFIG_FILE
223 Save a config file with the current options.
224 --path PATH
226 path Either a supported version control directory, a pre-generated
228 log file (see log commands or the custom log format), a Gource
229 conf file or '-' to read STDIN.
230 If path is ommited, gource will attempt to read a log from the
232 current directory.
233
236 View the log of the respository in the current path:
237 gource
239 View the log of a project in the specified directory:
241 gource my-project-dir
243 For large projects, generating a log of the project history may take a
245 long time. For centralized VCS like SVN, generating the log will put
246 load on the central VCS server.
247 In these cases, you may like to save a copy of the log for later use.
249 You can generate a log in the VCS specific log format using the
251 --log-command VCS option:
252 cd my-svn-project
254 `gource --log-command svn` > my-svn-project.log
255 gource my-svn-project.log
256 You can also have Gource write a copy of the log file in its own for‐
258 mat:
259 gource --output-custom-log my-project-custom.log
261
264 Use 'cvs2cl' to generate the log and then pass it to Gource:
265 cvs2cl --chrono --stdout --xml -g-q > my-cvs-project.log
267 gource my-cvs-project.log
268
271 If you want to use Gource with something other than the supported sys‐
272 tems, there is a pipe ('|') delimited custom log format:
273 timestamp - A unix timestamp of when the update occured.
275 username - The name of the user who made the update.
276 type - Single character for the update type - (A)dded, (M)odi‐
277 fied or (D)eleted.
278 file - Path of the file updated.
279 colour - A colour for the file in hex (FFFFFF) format. Optional.
280
283 See the guide on the homepage for examples of recording videos with
284 Gource:
285 http://code.google.com/p/gource/wiki/Videos
287
290 Visit the Gource homepage for guides and examples of using Gource with
291 various version control systems:
292 http://code.google.com/p/gource/
294
297 The time shown in the top left of the screen is set initially from the
298 first log entry read and is incremented according to the simulation
299 speed (--seconds-per-day).
300 Pressing SPACE at any time will pause/unpause the simulation. While
302 paused you may use the mouse to inspect the detail of individual files
303 and users.
304 TAB cycles through selecting the current visible users.
306 The camera mode, either tracking activity or showing the entire code
308 tree, can be toggled using the Middle mouse button.
309 You can drag the left mouse button to manually control the camera. The
311 right mouse button rotates the view.
312 Interactive keyboard commands:
314 (V) Toggle camera mode
316 (C) Displays Gource logo
317 (K) Toggle file extension key
318 (M) Toggle mouse visibility
319 (N) Jump forward in time to next log entry
320 (S) Randomize colours
321 (+-) Adjust simulation speed
322 (<>) Adjust time scale
323 (TAB) Cycle through visible users
324 (ESC) Quit
325
327 Written by Andrew Caudwell
328 Project Homepage: http://gource.googlecode.com/
330
332 Copyright (C) 2009 Andrew Caudwell (acaudwell@gmail.com)
333 This program is free software; you can redistribute it and/or
335 modify it under the terms of the GNU General Public License
336 as published by the Free Software Foundation; either version
337 3 of the License, or (at your option) any later version.
338 This program is distributed in the hope that it will be useful,
340 but WITHOUT ANY WARRANTY; without even the implied warranty of
341 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
342 GNU General Public License for more details.
343 You should have received a copy of the GNU General Public License
345 along with this program. If not, see <http://www.gnu.org/licenses/>.
346
348 Catalyst IT (catalyst.net.nz)
349 For supporting the development of Gource!
351 Gource(1)