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