The goals of a revision-control system (as provided by this site) are:

• to record temporal changes of collections of files,
• to permanently record each revision of a file, and
• to permit concurrent, heterogeneous collaboration in the editing of those files.

Bearing those in mind, one should consider the following before committing any changes to a repository:

• Do not commit automatically generated files. These typically include, for example:

  • compiled files such as *.o/*.obj files, or Java *.class and *.jar files, and executables generated from them;
  • Thumbs.db — the XP index or cache of thumbnail images for a folder;
  • Javadoc output, TeX DVIs, or other generated documentation (e.g. *.ps, *.pdf, *.bbl, *.aux, *.blg, *.log).

  Such files can change arbitrarily, simply because they get generated in each working copy using potentially very different software — different versions, different compilation options, different compilation targets. In other words, the differences are not related temporally, so version control is unsuited to record them. If you erroneously place them under version control, they will only frustrate other users working on different systems with their own working copies of the same repository.

  Their contribution to the volume of a repository also cannot easily be excised. Even after naïve removal (e.g., by svn rm), they still exist in earlier revisions and take up disc space. Genuine removal requires the repository to be taken off-line so it can be filtered.

  An SVN hook script is available to forbid commits of files with certain suffixes to help enforce this principle, and it is enabled by default on new repositories. The error message points users to this page. Administrators can reconfigure or disable the script after creation of the repository, if necessary.

• Avoid committing configuration files and data that refer to specific paths or hosts, unless these can be overridden by the user of a working copy without actually altering the files. Consider instead these options:

  • Keep default configuration in a template file, and arrange for your build scripts to copy it into an effective position when required, if the user hasn't already provided their own.

    For example, suppose your project requires a myprog.conf file, which the user is expected to edit to tailor the build to the local environment. You can't commit it to the repository because of the editing, but you want to provide some defaults so that the user does not have to write the whole thing from scratch. So create a file myprog.conf-orig with the defaults and commit that. Build myprog.conf from it locally if necessary.

  • Use features of your build environment to insert the user's configuration dynamically at build time, such that it overrides your defaults.

    For example, Make has an -include or sinclude directive which can search for a file in a user-specified path, but doesn't report an error if not found. Ant can import overriding properties with a <property resource="searchname" /> task.

• Take extra care not to commit passwords and other secrets or credentials. These are extremely tedious to remove.

• Refrain from committing obscene or offensive messages. These are also extremely tedious to remove, and could result in you losing your pride, your job, or a gonad.