Plan for Software Carpentry 2012 Boot Camp on Version Control¶
To explain version control and introduce Mercurial to researchers who have never used it before, or who want to understand it better.
Two hour interactive live workshop, using EasyMercurial and the Mercurial command-line tool.
The basic plan is:
- presentation introduction to version control in general (using either whiteboard drawings or a PowerPoint presentation)
- long worked example in which basic topics of version control are worked through using EasyMercurial and then some more advanced topics are returned to using the command-line tool
- closing remarks talking about other tools, other topics of interest etc
- A presentation introduction to the concept of version control.
- What is it for and why is it useful?
- What can go wrong without it?
- How does a version control system work?
- History + Collaboration
- Check that participants have EasyMercurial installed and working. All of the following exercises will be using EasyMercurial unless it says otherwise
- Worked example, part 1: Working by myself
- Topics: Initialising a repository, committing files, reading history, looking at diffs, reverting unwanted changes, going back in time to look at old versions
- We will be working on a recipe for fish stew for a future recipe book
- Make a new directory, create a text file
fishstew.txtin it, start adding an ingredients list, save
- Run up EasyMercurial, "Open" that directory, see
fishstew.txtin untracked file list, explain this
- Add file, commit, supply a message, note that we now have some history
- Make a change, note that files are marked as modified, note possible presence of backup file (ending ~ or .bak) from editor -- we'll come back to that in a moment
- A changeset records the state of all files, not just one file: add another file,
omelette.txtand add that
- Commit change, review history, look at the diff
- Digression: every action we're taking here corresponds to one command-line command: show hg log, hg diff etc
- Go back to that backup file in My Work, add it to ignored list, commit
- The history is not just for information: we can go back to the previous version by updating to it...
- ... and then a normal update gets us back to the latest version again
- Now, let's say this is the version we send off to our agent to see whether (s)he can sell it to a publisher. (Or whatever we do these days.) Tag it as v0.1 -- digression about sensible tag names on whiteboard?
- Make and commit another change, just to make the history more interesting
- What if we make a change and decide we don't want to commit it? Edit something, then hit Revert
- ... but we are still in big trouble if our computer fails. Thus:
- Worked example, part 2: Working by myself "with backups"
- Topics: Clone, push and pull, using an online repo
- Register an account on Bitbucket and create a new private repository
- Look up its URL
- In EasyMercurial, hit the Push button, enter URL, push to remote repo, check that the history is present and correct on the site
- Make another change locally, commit, push, and check the history on site again
- Exit EasyMercurial. Delete the local repository / working copy folder completely!
- Start EasyMercurial again, see that (sniff) the working copy is lost. Clone it again from Bitbucket and note that the history is all there
- Digression: Note command-line usage again, hg push, hg pull, hg clone: show a sequence of clones, modifying the last one and pushing back along the chain?
- Worked example, part 3: Introducing other developers
- Topics: Conflicts, merges
- Pair up and, in each pair, decide whose Bitbucket repo you will be working on and whose we'll just leave for now. (We should pair the "instructor" with someone as well)
- Remark: in real-world use, this could very well be the same person just using two different computers
- The second person in the pair should then clone the repository from Bitbucket
- Both people can then make some edits: they should edit the same file
- The second user should push their changes to the remote repo first
- The first user then tries to push. They should get the "Push failed... The local repository may have been changed" message
- Then the first user pulls instead. (Perhaps checks the Incoming list first?) History graph now shows two heads -- digression on sociological nature of conflict a la Greg if feeling expansive
- Hit Merge, get the merge window up. Do an "instructor-guided" merge
- Commit, push, get collaborator to pull
- Run annotate (blame) on the recipe to see who changed what and when
- Worked example, part 4: More sophisticated business at the command-line
hg archive: packaging from a tag
hg id: provenance when running experiments
hg bisect: finding the origin of bugs you can't see (analogy with
hg annotatefor finding bugs you can see)
Things not yet incorporated into the above: Copying and renaming files; Branching and merging amonst branches; Stuff that is different in other systems
Should we cover (named) branches and merges between them? I think yes, if there is time.
Against: perhaps a level of complication too far for a two-hour intro; Greg doesn't cover them in the Subversion version; lessons learned from Hg are not immediately applicable to git or Subversion because the branching methods are somewhat different.
For: they are much simpler to use in Mercurial than in Subversion!
The Software Carpentry Subversion course includes a quiz -- I like quizzes. Let's try adjusting the questions for Mercurial:
- Why is it a good idea to use version control on your projects? (Answer)
- Explain what the “master copy” and “working copy” of a repository are. To which copy do users make their changes? (Answer)
- Suppose you’ve created a new file on your computer that you want to put into the repository. How do you go about doing this? (Answer)
- Jon is working on a version-controlled project with Ainsley and Tommy. He wakes up early one day, ready to do some work on the project. What is the first thing he should do? (Answer)
- Tommy and Jon have up-to-date working copies, and are both editing a file that contains 10 lines of data. Jon makes a change to the fifth line, and commits his changes. Tommy makes a change to the first line of the file, and tries to commit. What will happen, and what should Tommy do next? (Answer)
- Ainsley and Jon are up-to-date, and are both editing the sixth line of a file. Jon commits his changes first. When Ainsley tries to commit, what will happen, and what should she do next? (Answer)
- How do you undo local changes to files that have not been committed? (Answer)
- How do you “undo” changes that have been committed? (Let’s assume you are at revision 10, and want to “go back” to revision 9.) (Answer)
- Give the shell commands you would use to accomplish the following tasks:
Check out the repository located at http://example.com/repo into the directory /cygwin/home/repo (Answer)
View the log of changes (Answer)
Add the file “experiment.txt” to the repository (Answer)
Commit the file to the repository. (Answer)
Update a working copy of a repository (Answer)