SoundSoftware Code Site

h1. Version Control Problems

Some problems that complete beginners face when trying to create and work with repositories using current version control systems.

h2. Subversion

 * Puzzlement over "recommended" trunk/branches/tags structure

When instructing people how to create new projects, it's arguably simplest to ignore this and go for a structure that places them directly in the project directory.  But that still results in confusion when checking out other people's projects that do have a difference between root URL and trunk URL.  As far as I can tell, this particular issue confuses or bites every user of SVN at some point, though not generally seriously (in the sense of getting the wrong results, rather than just e.g. checking out more than you bargained for).

Note, I'm not counting "difficulty in doing branch merges" etc as a problem for new users of Subversion -- most people will simply never use branches so it's not an issue.

 * Difference between repository and working copy

Not a problem for many people, but some seem to find the concepts confusing.  One problem here is that the tools don't make the distinction very clear, but do require you to understand the distinction -- for example, when uding an SVN front-end you are browsing the working copy (and cannot browse the repository directly) but when using a web interface to SVN you are always browsing the repository (and cannot see your working copy).

One tool that did a pretty good job here, whether by accident or design, was Visual SourceSafe -- I've always imagined this to be a big contributing factor in its popularity.

 * Requirement to update/merge/resolve before commit if someone else has modified the repository

A good user interface can make this workflow clearer

 * Forgetting to "svn add" new files

User interface should make a prominent note of files that have been created since the last commit

 * Forgetting to use svn when renaming or removing files

 * Admin help required for corrupted working copy because of sensitivity to changes in .svn directories (reported)

h2. Mercurial

 * Requirement to pull/update/merge/resolve/commit before pushing if someone else has modified the repository

A good user interface can make this workflow clearer (a bad one can make it almost impossible), but it is generally more complex than SVN because of:

 * Mystification over branches, particularly anonymous branch created when you pull before a merge

A good user interface can still help here by making the branch structure and origin of each change explicit -- many just pile up the change log in a single list.  Again, I'm generally not concerned with difficulties in deliberately using branches here as most people just won't, but with Hg unlike SVN you do need to be aware of branches because they happen whether you ask for them or not.  On the other hand, if the branch structure is made explicit, it arguably reflects better "what actually happened" than the linear change log (people really were working on the two different commits at the same time).

 * Forgetting to "hg add" new files

User interface should make a prominent note of files that have been created since the last commit

 * Forgetting to use hg when renaming or removing files

 * Lack of transparency about some config matters, such as the setting for my own name for commit logs, and the identity of the default push location

h2. Git

 * Forgetting to "git add" new files

User interface should make a prominent note of files that have been created since the last commit.  Note that git is friendlier than the others in how it deals with removing and renaming files.

What else?  I haven't really had any experience trying to explain Git to people.

The specific thing that bit _me_ with Git was pushing to a non-bare repo (i.e. trying to treat clones of repos on different machines as peers and push changes around between them), which led to some work that had been pushed to a repo subsequently being overwritten with work done locally in that repo but not yet committed.  It was only much more recently that I worked out what had happened, at the time I just thought my work had gone missing and swore never to use Git again.  Pushing to a non-bare repo is apparently now prohibited by default, though the terminology and concepts involved are arguably still pretty confusing.  Of course this would only have been an issue for people "running" their own repos -- if you always sync to Github or similar it would never bite you.