What should be in version control

And what not. There’s clear line between these two and one should never cross that line without very good reason.

Version control systems, such as git and SVN, are very popular around the globe and used in most projects. Version control systems allow saving individual changes to files, diffing those changes and ultimately rolling back the work to specific revision. But version control systems should not to be used to store all data your project needs.

So what you should put in version control system? At least:

• Source code files
• Scripts and other files you need to build software
• Text formatted documentation, such as README and LICENSE files
• Tool configuration files, such as clang-format settings and .gitignore
• All other text files that your project needs

Baseline for files in version control is that they are hand written text. So what should not be put in the version control and why?

• Generated files. Each person working with the repository should be able to generate these files with a push of a button — it’s not good idea to put them in version control as they only mess up your history once the generated files change
• Build artifacts. This should be clear — build artifacts just do not belong to the version control. Having them there would mean that every time source code changes, all related build artifacts would also be updated. Just DO NOT do it.
• IDE specific configuration files. Actually this is a bit ambiguous topic. Personally I don’t want to keep the IDE configuration files at least on top of the project repository but instead in some subfolder where people can copy or use a script to set up the repository for their IDE of choice (also using vim saves you the huzzle ;)).
• Binary documentation files. While storing documentation, such as pdfs or excel sheets, in the repository might make sense it does not actually bring any more value than you can rollback to specific version. You cannot diff the changes and see what has been changed and when. If you really need to store binary documents in your repository, at least consider using svn or git with the git-lfs extension to make it a bit less painful.
• Pre-compiled and source code of 3rd party dependencies. This means JAR files and other pre-compiled binaries as well as the 3rd party source code. The build environment should take care of fetching or building the necessary dependencies for you. Using right tools like a dependency manager such as gradle can help you a lot with this.
• All other binary content. This means tools (executables), images, audio, videos, database files and other files you cannot open with your text editor and read. Sometimes it’s necessary to have some images in the repository but you should always think twice before pushing them.

To prevent this kind of content ending in to the repository by accident, one should use ignoring of files by their types (such as .gitignore or svn:ignore). Also if you are using git you might want to setup global gitignore file to be used on all computers you work on.

If you liked the story, please press the ❤ button below (did you know that you can give more than one clap). Also please feel free to share this story!

About me

I am Heikki Hellgren, Software Expert and technology enthusiast working at Elektrobit Automotive. My interests are in software construction, tools, automatic testing and all the new and cool stuff like AI and autonomous driving. You can follow me on Medium and Twitter and check out my website for more information.

What should be in version control was originally published in Hacker Noon on Medium, where people are continuing the conversation by highlighting and responding to this story.