Approaching Rails Legacy Systems Chapter 2: Become a Git Historian

Reading Time: 4 minutes

To keep track of how a project has been changing through time is key to provide a big picture of what things have been changing and why. After all, the business logic or the domain required those changes to be recorded. Read this to know why it is important to keep an eye on a project's history.


Become a Git Historian

This is chapter 2 of a series of blog posts about some pieces of advice, tools, and tips you can consider when you arrive at a Rails project considered as Legacy.

In the previous chapter, we reviewed our project’s anatomy.

In this chapter, we are using Git and other tools related to it to find out more about our Rails Legacy System. But this time, it's our project's history turn.

First, I want us to understand 'history' as:

"The whole series of past events connected with someone or something".

When speaking about history in a Rails project, it's really important to check how our project has changed through time to get an idea of why things have been modified. Some of those adjustments were maybe done based on business logic, or maybe the domain required those changes.

Maybe, other changes happened because someone followed a particular path —which is a normal thing if you consider that every project is different and that there are infinite factors that can affect it in a positive or in a negative way.

In Software Development, a legacy system is outdated computing software that is still in use. Click To Tweet

In Software Development, a legacy system is outdated computing software that is still in use. That system still meets the needs it was originally designed for but doesn’t allow growth. What a legacy system does now for the project is all it will ever do. A legacy system’s older technology won’t allow it to interact with newer systems.

Git extras

To get a general summary of things about the project, like repo age, the number of commits, and who the people involved are we could use git-extras.

$ brew install git-extras
$ git summary

 project  : big_rails_jump
 repo age : 7 years
 active   : 1167 days
 commits  : 23794
 files    : 4084
 authors  :
  3392  Aaron Patterson             14.3%
  2596  David Heinemeier Hansson    10.9%
  2389  Yukihiro Matsumoto          10.0%
  2091  Lenny Kravitz               8.8%
  1017  Pedro Infante               4.3%
  1011  Tania Muñoz                 4.2%
   986  Edwin Cruz                  4.1%
   870  Juan Carlos Ruiz            3.7%
   857  Omar Vazquez                3.6%
   773  Jonathan Tapia              3.2%
   695  Alejandro Espinoza          2.9%
   667  Heriberto Perez             2.8%
   590  Jose David                  2.5%
   548  Samantha Bello              2.3%
   430  Juan Escutia                1.8%
   417  J Balvin                    1.8%
   309  Myles Kennedy               1.3%
   296  Federico Crespo             1.2%
   266  Dr Simi                     1.1%
   257  Tigger                      1.1%
   246  Emmanuel Delgado            1.0%
   234  Victor Velazquez            1.0%

Here is another interesting feature from git-extras, let's try git effort:

$ git effort --above 15 {src,lib}/*

Displays "effort" statistics. Currently, it shows just the number of commits per file, highlighting the parts with the most activity. The "active days" column is the total number of days when contributed modifications to this file were made.

git-extras has many interesting features that you can explore and use to get a better understanding of your project.

Git log

Ok, now let's understand how change on single objects works with git log.

$ git log --patch --stat Gemfile

commit f6043a0c731de894f05328da79f04b9456931074
Author: Ozmar Ugarte <>
Date:   Mon May 9 15:08:33 2016 -0400

    NPS delighted survey scheduling

    This commit was made only for testing purposes.
 Gemfile | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Gemfile b/Gemfile
index bbecfdf79..9b1fa9332 100644
--- a/Gemfile
+++ b/Gemfile
@@ -142,6 +142,9 @@ gem 'has_scope', '~> 0.6.0.rc'
 gem 'cocoon'
 gem 'sailthru-client', '~> 4.0.1'

+#Delighted nps
+gem 'delighted'
 # form object
 gem 'virtus', '~> 1.0.3'

As you can see, it will show why a specific update was made. Or, maybe it will just trigger more questions. But, at least you will be closer to your main goal, which is "understand what was the purpose of those changes".

Git History

Also, if you prefer the fancy way and see the timeline of a particular file, you can try git-history.

Now, let's use git-history, which is like a visual time machine where you can visually review any change on a specific file and understand its timeline.

Check this example out.

Look for Documentation (we're using Git as well)

As we look for documentation keep in mind and ask yourself the following:

  • Is there any documentation at all?
  • Is there good commentary on the code?
  • Do the names of things make sense?
  • Are the System Use Cases documented?
  • Is there someone in the team that understands the system?

We can use git whatchange doc to see logs and differences in our documentation, check the example above:

$ git whatchanged doc
commit e43e0fecfb5914ec0e72eadff73e90c0e14c7026
Author: Daniel Contreras <>
Date:   Thu Jan 28 19:32:35 2016 -0500

    Render diagram inline. Use AsciiDoc for the table of contents.

:100644 100644 13fa6c9d4 ff7935d08 R055 doc/client-system/     doc/client-system/README.adoc

It seems that we have a doc folder. 🎉🎉🎉 It also seems like the last time a document was modified was in 2016, so it’s time to start documenting your new progress. That would help you in the future, and any other developer that joins the team.

Extra: The README

There is a README? Well, yes. But it is so poor...

Hey, but don't worry, there are many templates you can use; like this example.

Wrap up

Here are more things to keep in mind:

  • Document everything you learn.
  • Keep documentation close to the code, simple is better.
  • You must understand the design/architecture.
  • Once you understand something, refine its documentation.

I hope you find this blogpost compelling. In the following chapter, we are going to cover some nice toolings for static analysis of your code.

You May Also Like