Using Pull Requests and Git Log to Learn a Project

Jumping into a new project is hard. People have been working on the code base potentially for many years! That’s a lot of technical knowledge to gather before you can start being productive. There’s probably thousands of files, maybe more than one project that drives 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. The Pull 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, 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 GitLab Issue Board As you can see, all I did was search their merge requests for and limited the search to . slash commands 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 ? has a flag you can use for searching through commit messages. git log git log --grep jaredready@Jareds-MBP gitlab (master)$ git log — grep=”slash command” — reversecommit 0eea8c885743575b0e93a98846b3663e9903aa66Author: Rémy Coutable Date: Thu Jun 30 17:34:19 2016 +0200 remy@rymai.me 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 normalparams in noteable Creation services— the logic is not in the models but in the Creation services, which isthe right place for advanced logic that has nothing to do with whatmodels should be responsible of!— UI/JS needs to be updated to handle notes which consist of commandsonly— 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 pull request, you’ll see this commit is actually the first commit of that pull request. The rest of the log from the command contains most of the rest of those commits. git log — grep=”slash command” — reverse To view the changes from this commit so you can see how the slash commands were implemented, we can use the command. git show 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 when you don’t have access to a pull request. Hopefully this makes jumping into new projects a little easier. git log