Never remove anything from your .gitignore file!

FacebooktwitterlinkedinmailFacebooktwitterlinkedinmailby feather

Here is a quick programming story with a simple moral. The moral is: don’t try to keep your codebase so lean and clean, that you actually re-introduce a problem you’ve already solved. In particular, never remove anything from your .gitignore file!

You got XML in my Javascript! is one resource for helping you make good .gitignore files is one resource for helping you make good .gitignore files

I recently rolled onto a software project with a number of other developers, from diverse backgrounds and locations. Because each developer used their[1] own preferred text editor, the .gitignore file for the project’s repository listed several specific editor config files and directories to exclude from version control.

One of developers, who was only contracted for three months, rolled off the project last week. He happened to have been a remote worker, and so was not in constant communication with the rest of the team, even while  on the project. This remote developer was something of a “code cowboy”, who thrived on working fast and dirty. Because we knew that he was a short-timer on the project, the rest of the developers had resigned themselves to letting his scope creep slip through.

A couple of days after the cowboy was officially done with the project, he submitted a pull request to fix an issue with one of the last features he had worked on. Probably because of his programming style, he didn’t notice that his final commit had seven extra XML files in it. I happened to review this pull request, and I was shocked to see those seven new XML files, in addition to a few changed lines in a Javascript file. Now, the cowboy had also been working on a section of code that dealt with XML data in the weeks before he left, and I thought this was his attempt to sneak some final hacks into that section of code. I balked, and asked him why he put unrelated code into this pull request.

After a lot of messaging back and forth, we found out had happened. The cowboy had been the last developer on the team who used a particular text editor, an editor that kept its preferences in a folder of XML files. One of the other developers, who had been on the project from the beginning with the cowboy and likes to keep the codebase “clean”, had removed the line in our .gitignore file that excluded that preference folder and its XML files.

Of course, this was a perfect little storm of coincidences. It was the beginning of a holiday week, and our team communication was not as good as it could have been. The project had been without a manager for a couple of weeks because of a transition in project managers, and the product owner had gone directly to the cowboy about making that last change.

My initial rejection of the code had been a “boy-who-cried-wolf” reaction. In this case, the remote developer hadn’t really meant to commit extra code. I hadn’t recognized the extra code for what it was—an oversight—because I was new to the project myself and wasn’t familiar with that text editor. In the end, the developer who had removed that entry in .gitignore quickly realized what had happened and cleaned up the pull request so that it could be merged without the extra preferences files.

Yours tools should make less work for you, not more

Everybody, and nobody, was at fault in this story. The cost was paid in extra, unnecessary communications and clean up work after the problem happened.

Much as I would like to blame the cowboy, the problem wouldn’t have happened if the other developer had not been overzealous to make sure the .gitignore file contained no “unnecessary” exclusions. Without the developer who used that editor, we didn’t need that exclusion, but if another new developer comes on-board who also uses that editor, or if the former developer comes back for an encore (as happened), then all of a sudden we need it again. The cognitive load of removing and re-adding a few bytes from a text file on demand is not worth the effort. It was a problem once, it was solved, and the solution should be left in place.

Think of this as a new corollary to Murphy’s Law: whatever you think no longer needs to be in your .gitignore, will need to be in your .gitignore as soon as you remove it.

The .gitignore file exists to lower that cognitive load. It is not like an extra function, or module, or code library that you tried and no longer use. Those things should be removed from the code base when they’re no longer used because they may confuse programmers reading the codebase in the future. (The dumbest code comment in the world is “This is no longer needed…”.) Unlike the rest of the code, the .gitignore is write-only: you needed to ignore some file, you added it to .gitignore, and neither you nor anyone else ever has to worry about it again.

Don’t worry about it again.

[1] After many years of worrying about prescriptive grammar and awkward phrasing like “he/she”, I have decided that using the plural for indefinite pronouns is the best way to be gender-neutral. Raising two smart kids, a son AND a daughter, helped me to that decision.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.