Using Pull/Merge Requests and Git Log to Learn a Project

Jumping into a new project is hard. People have been working on the code base for potentially years! That’s a lot of technical knowledge to gather before you can start being productive. There’s probably thousands of files, maybe several projects that drive the application. Where do you begin?

Photo Credit: Rajesh Sundaram

For some reason people think that browsing the source code is still the normal way of learning how a project works. I’m here to say no, that’s not ideal and there are better ways that have been around for quite awhile.


The Pull/Merge Request

This is the easiest to place to start if you’re using a Git hosting solution like GitHub, GitLab, BitBucket, etc. Projects contain the history of how every change came to be and the discussion around every change in the form of Pull or Merge Requests.

For example, GitLab has recently added some slash commands (think of your slash commands in Slack) to their issue system. I am curious how they implemented this. So let’s go browse their merged merge requests.

GitLab Issue Board

As you can see, all I did was search their merge requests for slash commands and limited the search to merged.

That top merge request looks promising. It’s the oldest and the title of it seems to indicate this is where the feature came in. Let’s check that request out and scroll down to see the changes.

GitLab Merge Request

The merge request will tell you exactly what changed and what was added to implement the feature. This request contains a lot of change so we won’t be going over it, nor is that the point of this article.

In just a few minutes we were able to find when a feature was added, who added the feature, and what changes were needed to implement the feature. This is a bit better than browsing source files looking for something looks like it might be related. It also gives you every bit of information you need if you want to go in and enhance the feature.


Git Log

So we’ve gone over basic searching through pull or merge requests to find out how a feature was implemented. How can we do this same kind of search using git log? git log has a — grep flag you can use for searching through commit messages.

jaredready@Jareds-MBP gitlab (master)$ git log — grep=”slash command” — reverse
commit 0eea8c885743575b0e93a98846b3663e9903aa66
Author: Rémy Coutable <remy@rymai.me>
Date: Thu Jun 30 17:34:19 2016 +0200
Support slash commands in noteable description and notes

Some important things to note:

— commands are removed from noteable.description / note.note
— commands are translated to params so that they are treated as normal
params in noteable Creation services
— the logic is not in the models but in the Creation services, which is
the right place for advanced logic that has nothing to do with what
models should be responsible of!
— UI/JS needs to be updated to handle notes which consist of commands
only
— the `/merge` command is not handled yet

Other improvements:

— Don’t process commands in commit notes and display a flash is note is only commands
— Add autocomplete for slash commands
— Add description and params to slash command DSL methods
— Ensure replying by email with a commands-only note works
— Use :subscription_event instead of calling noteable.subscribe
— Support :todo_event in IssuableBaseService

Signed-off-by: Rémy Coutable <remy@rymai.me>

If you’ll look back at the merge request, you’ll see this commit is actually the first commit of that merge request. The rest of the log from the git log — grep=”slash command” — reverse command contains most of the rest of those commits.

To view the changes from this commit so you can see how the slash commands were implemented, we can use the git show <sha> command.


Conclusion

I urge you to not blindly flail through the code base to figure out how a project works. Use the pull requests as an easy to read history and discussion of the project. Use the `git log` when you don’t have access to a pull request. This will make jumping into a new project easier on you and easier on the experienced maintainers, as they won’t need to explain where everything is located.