skip to Main Content

Using Gource to Visualize a GitRepo and Why a Non-Dev Cares

  • By , Engagement Manager & SEO Specialist, Culture Foundry

This blog is for beginners, and I mean beginners, like people who didn’t realize they have a terminal on their mac, or that the terminal is also referred to as a “Local”. That was me.. is me.. However, awhile back my developer boyfriend showed me this really beautiful tool that visualizes git repos called Gource, and I thought there was potential in that tool to help clients understand the complexity of development work in a very visually aesthetic way, more on that later.

Here you’ll learn how to set up your terminal and some fun things to do in there, and it’s so easy your grandma could follow these directions. Note: this is only for MacOS. If you have windows.. well ¯\_(ツ)_/¯.

Setting up and running Gource and saving that file to a MP4 file.

First let’s walk through setting up your Terminal:

  • Find your terminal!! Try Command+Space and type “Terminal” hitting enter will open your terminal window
  • To set up Git and Developer tools type:  
    git 

    Hit enter. This should walk you through an install to set up your terminal to be something other than just another unexplored part of your computer.

  • The easiest way to start installing the other tools is to get Homebrew setup in your terminal copy the following and paste it into your terminal:

     ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" brew doctor

    Let it run, and when it’s finished you’ll be able to easily install other things and have a little fun! 
          — try, 

    brew install cowsay

    then

    cowsay

    + whatever you want the cow to say`
          — Or you can watch the whole Star Wars Episode IV by

    brew install telnet

    and then

    brewtelnet towel.blinkenlights.nl

    I’m not joking… It’s all in text.. the amount of time this must have taken!! 

  • Okay, back to the matter at hand, let’s install Gource and FFmpg (turns your gource into a MP4). With Homebrew this is super easy!

    • Type in your terminal

      brew install ffmpg
    • when that is finished installing type

      brew install gource
  • Super freaking easy!
  • Now you’ll need a git repo. (If you don’t already have a github account, git one!)
  • You can search public repos here: https://github.com/search?q=repos&type=Repositories or if you have access to your company’s repos the same directions below apply.
  • Select one and find the Clone URL button,
    how to clone a repo using a url
  • For this example, I’ve done the work for you and found one that is awfully pretty, it’s called Travis Cookbooks https://github.com/travis-ci/travis-cookbooks
  • Once you have copied the clone URL go back to your terminal
  • Type  
    git clone {+ repo URL}
  • You’ll need to know the directory name of the repo you just cloned you, so if you type

    ls

    into your terminal window it will show you all your computer’s directories,

  • Note here we want (chosen because it was pretty and worked) 
    travis-cookbooks
  • You’re going to want to change directories (cd), so

    cd travis-cookbooks
  • You’re all set! Just type

    gource

    and watch the magic happen!!

  • Okay.. magic is messy.. And so is this gource video.. Fortunately there are a ton of different commands we can run to clean this up and make it extra simplified!
  • You can view some commands here: https://github.com/acaudwell/Gource/wiki/Controls or

    man gource

    which will bring up a directory of commands you can use,

    q

    to get out of there, btw.

  • I really liked the commands that Fully Baked created for this http://www.fullybaked.co.uk/articles/getting-gource-running-on-osx
gource --hide dirnames,filenames --seconds-per-day 0.1 --auto-skip-seconds 1 -1280x720 -o - | ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i - -vcodec libx264 -preset ultrafast -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 gource.mp4

If you don’t want to create the movie just omit the:

-o- |  ffmpeg -y -r 60-f image2pipe -vcodec ppm -i --vcodec libx264 -preset ultrafast -pix_fmt yuv420p -crf 1-threads 0-bf 0 gource.mp4

If you want to change the name of the movie rename it from `gource.mp4` to `yourmoviename.mp4`

  • Now you are a senior engineer go forth and build a mobile responsive website! … oh wait.. None of the above is going to get you to be a senior engineer, let’s leave all that to the pros!

Now for the moment you’ve been waiting for!! Here is this website’s Git Repo Visualization:

You can note complete rebuilds from migration of Drupal to ModX, and the recent updates to the site’s rebuild.

How this Bridges the Client/Developer Divide:

Now to the real why of it all, when I did this project for our Hackfest here at Culture Foundry, I was surprised by all that I learned. The main intention was to use Gource to create a mp4 that could be shared with clients, but maybe you are thinking, “uh.. Why would I do that?”.

As an Engagement Manager, I often find myself defending time and cost of development projects. The nuances of development are often lost on everyone but the developers; clients want it yesterday, engagement/project managers want it now. However, there is a lot involved each time a developer touches lines of code, even for a small change on the site. This is especially true if that site isn’t current or new, and even more so, if that site was inherited legacy code from a previous development team. Websites are like cars, and if you ignore that barely audible knocking for long enough, eventually it will turn into a big expensive problem. Preventative site maintenance is way better than 1am mission critical site failures.

Developers are important and should be valued for the hard work they do. It’s not flipping a switch, sometimes it involves a lot of trial and error. Especially when one missing hyphen is the difference between broken and working, programming is attention to detail, so much reading, and a lot of troubleshooting. The more we can help our clients better understand development through visualizations like gource or educating them with honest conversations about the states of their website the better.

Run gource with the dates set between the start of a project and the end of a project, you can show your clients how their site grew and the work that was done. It’s a lot of touches, a lot of work, a lot of troubleshooting. Hopefully, you have a great team of solution finding developers, and hopefully, you show them respect and take a moment to ponder the complicated work they do.

On a personal anecdote, I once went to a Project Manager meet up, and was honestly a bit appalled by the amount of dev bashing that was happening. I won’t go into it, but I’ve always considered my role as an Engagement Manager (that’s what we call PMs here) as a bridge between my development team and my clients, my job is to keep open lines of communication and have hard conversations. On the other hand, the EM/PM’s allegiance is to the project, and to do as much as I can in order to help solve my clients pain points and trust my developers to have solutions to address those pain points.

There is never going to be a day when I open my terminal and fix a client’s website, but understanding how development works and how complicated it can be is important to respecting and valuing my team. To put it in perspective, I watched my boyfriend set up and run this whole project in about 5 minutes, this project took me 3.5 hours to figure out and run. I broke things (a lot), googled and troubleshooted more times than I care to admit. Development isn’t easy work, and devs usually don’t get to be on the happy satisfied calls with clients once their work is complete. It’s on to the next problem to solve. Burnout is high for developers, so take a moment and say “Woah! Great job! Thanks!”.
In conclusion, programming isn’t easy work for devs, vendor management isn’t easy work for clients, and project management isn’t easy work. However, if we take the time to understand the nuances and special skill sets of each other’s work, maybe we can have healthier relationships with our teams as a whole.

TL:DR, Set up Gource, show your clients, it’s pretty even if they don’t get it. Trust your developers and manage client expectations with compassion and education.

TTFN,
Laura

Back To Top