Source Code Visualization Using Gource

Found this visualization tool, Gource, while surfing. Decided to try it out on the project I have been working on for the past year. Installation and generation instruction as follow for Ubuntu 12.10.


1. Install the necessary softwares. FFmpeg, the video encoder, is needed to generate the video.
$ sudo apt-get install gource ffmpeg

2. Before we can visualize anything, we must generated the log file. If you're not sure the log command for your version control software, just use the --log-command flag as shown. I am using Subversion for this example.
$ gource --log-command svn
svn log -r 1:HEAD --xml --verbose --quiet

3. Go into your project folder and generate the log file.
$ svn log -r 1:HEAD --xml --verbose --quiet > project.xml

4. Visualize the log file and be amazed
$ gource project.xml

5. By default, Gource will show everything. However, sometimes we need customize the visual output to hide certain sensitive information and adjust the screen resolution. Play with the settings to get the best visual output. Customization very much dependent on the size of the log file and the number of developers. This process can increase disk I/O rate, you may experience some slowness.
$ time gource --camera-mode track --seconds-per-day 0.25 --hide date,dirnames,files,filenames,usernames -640x360 project.xml -o gource.ppm

real    2m6.712s
user    0m40.415s
sys     0m47.443s

Two important notes on reducing the file size. First, I compressed 4 days log into one day using the (--seconds-per-day 0.25) flag. Second, Gource core dumped on me when I tried using resolution of 426x240, the lowest resolution suggested by YouTube to maintain 16:9 aspect ratio. Hence, I have to switched back to 640x360.

6. In step 5, we have generated an uncompressed sequence of screenshot in PPM format (gource.ppm). Now we are going to encode the PPM file to create the video to be uploaded later to YouTube. Following the encoding instruction,
$ time ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i gource.ppm -vcodec libx264 -preset ultrafast -threads 4 -bf 0 gource.mp4

real    1m11.968s
user    0m20.273s
sys     0m33.950s

7. Upload the video to YouTube. See video above. By the way, the blue user icon is me.

No comments:

Post a Comment