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.

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 terminology confusing

 * 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

 * 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

h3. 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.  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.