Should I Keep My Project Files Under Version Control

Should I keep my project files under version control?

You do want to keep in version control any portable setting files,

meaning:

Any file which has no absolute path in it.

That includes:

• .project,
• .classpath (if no absolute path used, which is possible with the use of IDE variables, or user environment variables)
• IDE settings (which is where i disagree strongly with the 'accepted' answer). Those settings often includes static code analysis rules which are vitally important to enforce consistently for any user loading this project into his/her workspace.
• IDE specific settings recommandations must be written in a big README file (and versionned as well of course).

Rule of thumb for me:

You must be able to load a project into a workspace and have in it everything you need to properly set it up in your IDE and get going in minutes.

No additional documentation, wiki pages to read or what not.

Load it up, set it up, go.

best practice in storing non-source files under version control

You added in a comment:

The problem I have with this is that I don't care about the version history of those zip/video files, as long as they're the newest ones, there is no problem.

That means you have a linear workflow of development, only working on the LATEST of one main branch.

You do not seem to deal with the phase "after release", where you have to:

• maintain what runs in production
• develop small evolutions...
• ..while doing massive refactoring for experimenting some big evolutions

In the last three cases, the question of "what were the exact images, videos and zip files "I have to use" or "I was using at the time" might become important.

Anyhow, if you feel SVN do not handle them appropriately, I would still recommend having some way to remember that, for SVN revision xxx to yyy, you were using the version 'z' of your set of binaries.

For that, you could setup an external repository like Maven. See question "Is it acceptable/good to store binaries in SVN?" (my answer in that question is near the top of the page, but I link directly to Evan's answer as he mentions Maven).

Should IDE project files be put under source control?

One simple question: Do you need them to build your code? If not, then they're artefacts, not source files, and have no place being in the source control system.

Things like your editor color preferences or keybindings are not part of the build system. Compiler flags and so on are.

We store everything that's needed to build, down to the operating system install disks and required configuration. Anal-retentive doesn't even come close to describing us :-) If we could store the hardware, we would (we have to make do with storing a document detailing the hardware specs).

We also occasionally test our capability to build the development environment from scratch using only what's stored in the repositories. Failure there means that we;re not covered in terms of disaster recovery.

What to put under version control?

Rules of thumb:

1. Include everything which has an influence on the build result (compiler options, file encodings, ASCII/binary settings, etc.)
2. Include everything to make it possible to open the project from a clean checkout and being able to compile/run/test/debug/deploy it without any further manual intervention
3. Don't include files which contain absolute paths
4. Avoid including personal preferences (tab size, colors, window positions)

Follow the rules in this order.

[Update] There is always the question what should happen with generated code. As a rule of thumb, I always put those under version control. As always, take this rule with a grain of salt.

My reasons:

Versioning generated code seems like a waste of time. It's generated right? I can get it back at a push of a button!

Really?

If you had to bite the bullet and generate the exact same version of some previous release without fail, how much effort would it be? When generating code, you not only have to get all the input files right, you also have to turn back time for the code generator itself. Can you do that? Always? As easy as it would be to check out a certain version of the generated code if you had put it under version control?

And even if you could, could you ever be sure that didn't miss something?

So on one hand, putting generated code under version control make sense since it makes it dead easy to do what VCS are meant for: Go back in time.

Also it makes it easy to see the differences. Code generators are buggy, too. If I fix a bug and have 150'000 files generated, it helps a lot when I can compare them to the previous version to see that a) the bug is gone and b) nothing else changed unexpectedly. It's the unexpected part which you should worry about. If you don't, let me know and I'll make sure you never work for my company ever :-)

The major pain point of code generators is stability. It doesn't do when your code generator just spits out a random mess of bytes every time you run (well, unless you don't care about quality). Code generators need to be stable and deterministic. You run them twice with the same input and the output must be identical down to least significant bit.

So if you can't check in generated code because every run of the generator creates differences that aren't there, then your code generator has a bug. Fix it. Sort the code when you have to. Use hash maps that preserve order. Do everything necessary to make the output non-random. Just like you do everywhere else in your code.

Generated code that I might not put under version control would be documentation. Documentation is somewhat of a soft target. It doesn't matter as much when I regenerate the wrong version of the docs (say, it has a few typos more or less). But for releases, I might do that anyway so I can see the differences between releases. Might be useful, for example, to make sure the release notes are complete.

I also don't check in JAR files. As I do have full control over the whole build and full confidence that I can get back any version of the sources in a minute plus I know that I have everything necessary to build it without any further manual intervention, why would I need the executables for? Again, it might make sense to put them into a special release repo but then, better keep a copy of the last three years on your company's web server to download. Think: Comparing binaries is hard and doesn't tell you much.

.classpath and .project - check into version control or not?

Definitively yes, as I said in "Do you keep your project files under version control?"

"Load it up, set it up, go."

But... this is actually true only for recent Eclipse3.5 settings, where build paths support relative paths:

---

And Eclipse3.6 would be better, as it supports relative paths for path variables in Linked Resources:

(since 3.6M5)

Which files generated by Autotools should I keep in version control repository?

You should not keep any files under version control that are not hand-edited. That means any generated file should be ignored by the version control system. I basically put only the following under version control:

• configure.ac
• Makefile.am
• the documentation files such as AUTHORS, NEWS etc.
• Makefile.am in subdirectories

To address the point of having a "ready-to-install" version brought up by Scharron, some people include a script in the project's root directory, called bootstrap or autogen.sh, that you run once when you check a fresh copy out. You can see an example in one of my projects here. For a simpler project, your autogen.sh really only needs to consist of one line:

autoreconf --install || exit 1

although some people prefer to run ./configure automatically at the end of autogen.sh.

Why not track all the generated files in version control? Because their contents depend on the machine you are building on, the version of autotools you generated them with, and the phase of the moon. Any time any of these changes, the generated autotools files will change, and you will get a lot of junk in your commits.

Also, anyone who checks your code out of version control in order to build it should be expected to have proper development tools installed, so you really don't need to worry about people running into trouble because of missing autotools.

What VonC says about C projects coming with a configure file to generate the Makefiles is true for source code distributions (the .tar.gz file that you get when you type make dist) but not necessarily for freshly checked out copies from version control.

Why should I put files inside .idea folder under version control?

This is more of an opinion rather than answer, but you shouldn't put any of your workspace-related files into the repository. Every developer has his own configurations, application and server stack and I don't need to know that you're using NetBeans (.nbproject directory) and you don't need to know that I'm using PHPStorm (.idea). Repository should contain only project-related files, eg.:

• source code,
• default configurations,
• templates,
• libraries,
• documentation,
• 3rd party configurations (Travis, Composer),

and so on.

Are all files within a C# Project necessary to put under version control?

Not everything under the project folder is a part of the project.

Looking in Visual Studio, in the Solution Explorer, you can see the files that are actually part of the project. In the folder, though, you have the bin and obj folders, which contain temporary and output files. You can also find any number of old files, remains, copied files - all of which aren't compiled and don't find their way to the final product.

Some languages or IDEs look at the folder content as part of the project. Visual Studio manages it internally, in the .CSPROJ files.

So, to answer your question, the files that should be part of source control are the .cs files, .csproj files, .sln, .config and other files that are compiled or part of the project content - scripts, images and so on. The best way not to miss anything, on one hand, and not to add extraneous files is to use a Visual Studio source-control plugin, and do the check-in/check-out operations within VS.

When working with Eclipse, should I add the workspace to the source control?

I would not add the complete workspace, but I would add the .classpath and .project files (as well as the source, of course) so that you can recreate the project if needbe.

---

Related Topics