-{% extends "_base.html" %}
+{% extends "templates/_base.html" %}
{% block file_metadata %}
<meta name="title" content="Version Control With Subversion" />
{% endblock file_metadata %}
{% block content %}
- <ol class="toc">
- <li><a href="#s:basics">Basic Use</a></li>
- <li><a href="#s:merge">Merging Conflicts</a></li>
- <li><a href="#s:rollback">Recovering Old Versions</a></li>
- <li><a href="#s:setup">Setting up a Repository</a></li>
- <li><a href="#s:provenance">Provenance</a></li>
- <li><a href="#s:summary">Summing Up</a></li>
- </ol>
+ <ol class="toc">
+ <li><a href="#s:basics">Basic Use</a></li>
+ <li><a href="#s:merge">Merging Conflicts</a></li>
+ <li><a href="#s:rollback">Recovering Old Versions</a></li>
+ <li><a href="#s:setup">Setting up a Repository</a></li>
+ <li><a href="#s:provenance">Provenance</a></li>
+ <li><a href="#s:summary">Summing Up</a></li>
+ </ol>
+
+<p>
+ Wolfman and Dracula have been hired by Universal Missions
+ (a space services spinoff from Euphoric State University)
+ to figure out where the company should send its next planetary lander.
+ They want to be able to work on the plans at the same time,
+ but they have run into problems doing this in the past.
+ If they take turns,
+ each one will spend a lot of time waiting for the other to finish.
+ On the other hand,
+ if they work on their own copies and email changes back and forth
+ they know that things will be lost, overwritten, or duplicated.
+</p>
+
+<p>
+ The right solution is to use a
+ <a href="glossary.html#version-control-system">version control system</a>
+ to manage their work.
+ Version control is better than mailing files back and forth because:
+</p>
+
+<ol>
+
+ <li>
+ It's hard (but not impossible) to accidentally overlook or overwrite someone's changes,
+ because the version control system highlights them automatically.
+ </li>
+
+ <li>
+ It keeps a record of who made what changes when,
+ so that if people have questions later on,
+ they know who to ask
+ (or blame).
+ </li>
+
+ <li>
+ Nothing that is committed to version control is ever lost.
+ This means it can be used like the "undo" feature in an editor,
+ and since all old versions of files are saved
+ it's always possible to go back in time to see exactly who wrote what on a particular day,
+ or what version of a program was used to generate a particular set of results.
+ </li>
+
+</ol>
+
+<div class="box">
+ <h3>Nothing's Perfekt</h3>
+
+ <p>
+ Version control systems do have one important shortcoming.
+ While it is easy for them to find, display, and merge differences in text files,
+ images, MP3s, PDFs, or Microsoft Word or Excel files aren't stored as text—they
+ use specialized binary data formats.
+ Most version control systems don't know how to deal with these formats,
+ so all they can say is, "These files differ."
+ Reconciling those differences will probably require use of an auxiliary tool,
+ such as an audio editor
+ or Microsoft Word's "Compare and Merge" utility.
+ </p>
+</div>
+
+<p>
+ The rest of this chapter will explore how to use
+ a popular open source version control system called Subversion.
+</p>
+
+<div class="guide">
+ <h2>For Instructors</h2>
+
+ <p class="fixme">explain</p>
+
+ <div class="prereq">
+ <h3>Prerequisites</h3>
+ <p class="fixme">prereq</p>
+ </div>
+
+ <div class="notes">
+ <h3>Teaching Notes</h3>
+ <ul>
+ </ul>
+ </div>
+
+</div>
+
+<section id="s:basics">
+ <h2>Basic Use</h2>
+
+ <div class="understand">
+ <h3>Learning Objectives:</h3>
+ <ul>
+ <li>Draw a diagram showing the places version control stores information.</li>
+ <li>Check out a working copy of a repository.</li>
+ <li>View the history of changes to a project.</li>
+ <li>Explain why working copies of different projects should not overlap.</li>
+ <li>Add files to a project.</li>
+ <li>Commit changes made to a working copy to a repository.</li>
+ <li>Update a working copy to get changes from the repository.</li>
+ <li>Compare the current state of a working copy to the last update from the repository, and to the current state of the repository.</li>
+ <li>Explain what "version 123 of <code>xyz.txt</code>" actually means.</li>
+ </ul>
+ </div>
+
+ <p>
+ A version control system keeps the master copy of a file
+ in a <a href="glossary.html#repository">repository</a>
+ located on a <a href="glossary.html#server">server</a>—a computer
+ that is never used directly by people,
+ but only by their programs
+ (<a href="#f:repository">Figure 1</a>).
+ No-one ever edits the master copy directly.
+ Instead,
+ Wolfman and Dracula each have a <a href="glossary.html#working-copy">working copy</a>
+ on their own machines.
+ They can each edit their working copies whenever and however they want.
+ </p>
+
+ <figure id="f:repository">
+ <img src="svn/repository.png" alt="Repositories and Working Copies" />
+ <figcaption>Figure 1: Repositories and Working Copies</figcaption>
+ </figure>
+
+ <p id="a:commit">
+ When Wolfman is ready to share his changes with Dracula,
+ he <a href="glossary.html#commit">commits</a> his work to the repository
+ (<a href="#f:workflow">Figure 2</a>).
+ Dracula can then <a href="glossary.html#update">update</a> his working copy
+ to get those changes when he's ready for them.
+ And of course,
+ when Dracula finishes working on something,
+ he can commit and so that Wolfman can update.
+ </p>
+
+ <figure id="f:workflow">
+ <img src="svn/workflow.png" alt="Sharing Files Through Version Control" />
+ <figcaption>Figure 2: Sharing Files Through Version Control</figcaption>
+ </figure>
+
+ <p>
+ If this is all there was to version control,
+ it would be no better than FTP or Dropbox.
+ But what if Dracula and Wolfman change their working copies at the same time?
+ If Wolfman commits first,
+ his changes are simply copied to the repository
+ (<a href="#f:merge_first_commit">Figure 3</a>):
+ </p>
+
+ <figure id="f:merge_first_commit">
+ <img src="svn/merge_first_commit.png" alt="Wolfman Commits First" />
+ <figcaption>Figure 3: Wolfman Commits First</figcaption>
+ </figure>
+
+ <p class="continue">
+ If Dracula now tries to commit something that would overwrite Wolfman's changes
+ the version control system detects the <a href="glossary.html#conflict">conflict</a>,
+ halts the commit,
+ and tells Dracula that there's a problem
+ (<a href="#f:merge_second_commit">Figure 4</a>):
+ </p>
+
+ <figure id="f:merge_second_commit">
+ <img src="svn/merge_second_commit.png" alt="Dracula Has a Conflict" />
+ <figcaption>Figure 4: Dracula Has a Conflict</figcaption>
+ </figure>
+
+ <p class="continue">
+ Dracula must <a href="glossary.html#resolve">resolve</a> that conflict
+ before the version control system will allow him to commit his work.
+ He can accept what Wolfman did,
+ replace it with what he has done,
+ or write something new that combines the two—that's up to him
+ (<a href="#f:merge_resolve">Figure 5</a>).
+ Once he has cleaned things up, he can go ahead and try committing again.
+ If all of the conflicts have been resolved,
+ the version control will accept it this time.
+ </p>
+
+ <figure id="f:merge_resolve">
+ <img src="svn/merge_resolve.png" alt="Resolving the Conflict" />
+ <figcaption>Figure 5: Resolving the Conflict</figcaption>
+ </figure>
+
+ <div class="box">
+ <h3>Forgiveness vs. Permission</h3>
<p>
- Suppose that Wolfman and Dracula have been hired by Universal Monsters Inc.
- to figure out where the company should put its next secret lair.
- They want to be able to work on the plans at the same time,
- but they have run into problems doing this in the past.
- If they take turns,
- each one will spend a lot of time waiting for the other to finish.
- On the other hand,
- if they work on their own copies and email changes back and forth
- they know that things will be lost, overwritten, or duplicated.
+ Old-fashioned version control systems prevented conflicts from happening
+ by <a href="glossary.html#lock">locking</a> the master copy
+ whenever someone was working on it.
+ This <a href="glossary.html#pessimistic-concurrency">pessimistic</a> strategy
+ guaranteed that a second person (or monster)
+ could never make changes to the same file at the same time,
+ but it also meant that people had to take turns editing files.
</p>
<p>
- The right solution is to use a <a href="glossary.html#version-control-system">version control system</a>
- to manage their work.
- Version control is better than mailing files back and forth because:
+ Most of today's version control systems use
+ an <a href="glossary.html#optimistic-concurrency">optimistic</a> strategy instead:
+ people are always allowed to edit their working copies,
+ and if a conflict occurs,
+ the version control system helps them sort it out after the fact.
</p>
+ </div>
- <ol>
-
- <li>
- It's hard (but not impossible) to accidentally overlook or overwrite someone's changes,
- because the version control system highlights them automatically.
- </li>
-
- <li>
- There are no arguments about whose copy is the most up to date.
- </li>
-
- <li>
- Nothing that is committed to version control is ever lost.
- This means it can be used like the "undo" feature in an editor,
- and since all old versions of files are saved
- it's always possible to go back in time to see exactly who wrote what on a particular day,
- or what version of a program was used to generate a particular set of results.
- </li>
-
- </ol>
+ <p>
+ To see how this actually works,
+ let's assume that the Mummy
+ (Dracula and Wolfman's boss)
+ has already put some notes in a version control repository
+ whose URL is <code>https://universal.software-carpentry.org/explore</code>.
+ Every repository has an address like this that uniquely identifies the location of the master copy.
+ </p>
- <p>
- Version control systems do have one important shortcoming.
- While it is easy for them to find, display, and merge differences in text files,
- images, MP3s, PDFs, or Microsoft Word or Excel files aren't stored as text—they
- use specialized binary data formats.
- Most version control systems don't know how to deal with these formats,
- so all they can say is, "These files differ."
- The rest is up to you.
- </p>
+ <div class="box">
+ <h3>There's More Than One Way To Do It</h3>
<p>
- Even with this limitation,
- version control is one of the most important concepts in this book.
- The rest of this chapter will explore how to use Subversion,
- a popular open source version control system.
+ We will drive Subversion from the command line in our examples,
+ but if you prefer using a GUI,
+ there are many for you to choose from.
+ Please see the <a href="ref.html#s:svn:gui">reference</a> for links.
</p>
-
- <section id="s:basics">
-
- <h2>Basic Use</h2>
-
- <div class="understand" id="u:basics">
- <h3>Understand:</h3>
- <ul>
- <li>Where version control stores information.</li>
- <li>How to check out a working copy of a repository.</li>
- <li>How to view the history of changes to a project.</li>
- <li>Why working copies of different projects should not overlap.</li>
- <li>How to add files to a project.</li>
- <li>How to submit changes made locally to a project's master copy.</li>
- <li>How to update a working copy to get changes made to the master.</li>
- <li>How to check the status of a working copy.</li>
- </ul>
- </div>
-
- <p>
- A version control system keeps the master copy of a file
- in a <a href="glossary.html#repository">repository</a>
- located on a <a href="glossary.html#server">server</a>—a computer
- that is never used directly by people,
- but only by their programs
- (<a href="#f:repository">Figure XXX</a>).
- No-one ever edits the master copy directly.
- Instead,
- Wolfman and Dracula each have a <a href="glossary.html#working-copy">working copy</a>
- on their own computer.
- This lets them make whatever changes they want whenever they want.
- </p>
-
- <figure id="f:repository">
- <img src="svn/repository.png" alt="A Version Control Repository" />
- </figure>
-
- <p id="a:commit">
- As soon Wolfman is ready to share his changes,
- he <a href="glossary.html#commit">commits</a> his work to the repository
- (<a href="#f:workflow">Figure XXX</a>).
- Dracula can then <a href="glossary.html#update">update</a> his working copy to get those changes.
- And of course,
- when Dracula finishes working on something,
- he can commit and then Wolfman can update.
- </p>
-
- <figure id="f:workflow">
- <img src="svn/workflow.png" alt="Version Control Workflow" />
- </figure>
-
- <p>
- But what if Dracula and Wolfman make changes to the same part of their working copies?
- Old-fashioned version control systems prevented this from happening
- by <a href="glossary.html#lock">locking</a> the master copy
- whenever someone was working on it.
- This <a href="glossary.html#pessimistic-concurrency">pessimistic</a> strategy
- guaranteed that a second person (or monster)
- could never make changes to the same file at the same time,
- but it also meant that people had to take turns.
- </p>
-
- <p>
- Most of today's version control systems use
- an <a href="glossary.html#optimistic-concurrency">optimistic</a> strategy instead.
- Nothing is ever locked—everyone is always allowed to edit their working copy.
- This means that people can make changes to the same part of the paper,
- but that's actually fairly uncommon in a well-run project,
- and when it <em>does</em> happen,
- the version control system helps people reconcile their changes.
- </p>
-
- <p>
- For example,
- if Wolfman and Dracula are making changes at the same time,
- and Wolfman commits first,
- his changes are simply copied to the repository
- (<a href="#f:merge_first_commit">Figure XXX</a>):
- </p>
-
- <figure id="f:merge_first_commit">
- <img src="svn/merge_first_commit.png" alt="Wolfman Commits First" />
- </figure>
-
- <p class="continue">
- If Dracula now tries to commit something that would overwrite Wolfman's changes
- the version control system stops him
- and points out the <a href="glossary.html#conflict">conflict</a>
- (<a href="#f:merge_second_commit">Figure XXX</a>):
- </p>
-
- <figure id="f:merge_second_commit">
- <img src="svn/merge_second_commit.png" alt="Dracula Has a Conflict" />
- </figure>
-
- <p class="continue">
- Dracula must <a href="glossary.html#resolve">resolve</a> that conflict
- before the version control system will allow him to commit his work.
- He can accept what Wolfman did,
- replace it with what he has done,
- or write something new that combines the two—that's up to him.
- Once he has fixed things, he can go ahead and commit.
- </p>
-
- <p>
- Let's start by looking at the basic workflow we use
- when working with a version control system.
- To keep things simple,
- we'll assume that the Mummy has already put some notes in a version control repository
- on the <code>universal.software-carpentry.org</code> server.
- The full URL for this repository is <code>https://universal.software-carpentry.org/monsters</code>.
- Every repository has an address like this that uniquely identifies the location of the master copy.
- </p>
-
- <p>
- It's Monday night.
- In order to get a working copy on his computer,
- Dracula has to <a href="glossary.html#check-out">check out</a> a copy of the repository.
- He only has to do this once per project:
- once he has a working copy,
- he can update it over and over again to get other people's work:
- </p>
-
- <div class="box">
- <h3>There's More Than One Way To Do It</h3>
-
- <p>
- We will drive Subversion from the command line in our examples,
- but if you prefer using a GUI,
- there are many for you to choose from:
- </p>
-
- <ul>
-
- <li>
- <a href="http://tortoisesvn.net/">TortoiseSVN</a>
- is integrated into the Windows desktop,
- so there's no separate GUI as such.
- </li>
-
- <li>
- <a href="http://rapidsvn.tigris.org/">RapidSVN</a> is free,
- and runs on many platforms,
- but some users report difficulties installing it.
- </li>
-
- <li>
- Syntevo's <a href="http://www.syntevo.com/smartsvn/index.html">SmartSVN</a> isn't free,
- but it costs less than most textbooks,
- and is more stable (and has a friendlier interface) than RapidSVN.
- </li>
-
- </ul>
-
- </div>
-
- <p>
- While in his home directory,
- Dracula types the command:
- </p>
+ </div>
+
+ <p>
+ It's Monday morning,
+ and Dracula has just joined the project.
+ In order to get a working copy on his computer,
+ Dracula has to <a href="glossary.html#check-out">check out</a> a copy of the repository.
+ He only has to do this once per project:
+ once he has a working copy,
+ he can update it over and over again to get other people's work.
+ </p>
+
+ <p>
+ While in his home directory,
+ Dracula types the command:
+ </p>
<pre>
-$ <span class="in">svn checkout https://universal.software-carpentry.org/monsters</span>
+$ <span class="in">svn checkout https://universal.software-carpentry.org/explore</span>
</pre>
- This creates a new directory called <code>monsters</code>
- and fills it with a copy of the repository's contents
- (<a href="#f:example_repo">Figure XXX</a>).
- </p>
+ <p class="continue">
+ This creates a new directory called <code>explore</code>
+ and fills it with a copy of the repository's contents
+ (<a href="#f:example_repo">Figure 6</a>).
+ </p>
<pre>
-<span class="out">A monsters/jupiter
-A monsters/mars
-A monsters/mars/mons-olympus.txt
-A monsters/mars/cydonia.txt
-A monsters/earth
-A monsters/earth/himalayas.txt
-A monsters/earth/antarctica.txt
-A monsters/earth/carlsbad.txt
+<span class="out">A explore/jupiter
+A explore/mars
+A explore/mars/mons-olympus.txt
+A explore/mars/cydonia.txt
+A explore/earth
+A explore/earth/himalayas.txt
+A explore/earth/antarctica.txt
+A explore/earth/carlsbad.txt
Checked out revision 6.</span>
</pre>
- <figure id="f:example_repo">
- <img src="svn/example_repo.png" alt="Example Repository" />
- </figure>
+ <figure id="f:example_repo">
+ <img src="svn/example_repo.png" alt="Example Repository" />
+ <figcaption>Figure 6: Example Repository</figcaption>
+ </figure>
- Dracula can then go into this directory
- and use regular shell commands to view the files:
- </p>
+ <p class="continue">
+ Dracula can then go into this directory
+ and use regular shell commands to view the files:
+ </p>
<pre>
-$ <span class="in">cd monsters</span>
+$ <span class="in">cd explore</span>
$ <span class="in">ls</span>
<span class="out">earth jupiter mars</span>
$ <span class="in">ls *</span>
cydonia.txt mons-olympus.txt</span>
</pre>
- <div class="box">
-
- <h3>Don't Let the Working Copies Overlap</h3>
+ <div class="box">
+ <h3>Don't Let the Working Copies Overlap</h3>
- It's very important that the working copies of different project do not overlap;
- in particular,
- we should never try to check out one project inside a working copy of another project.
- The reason is that Subversion stories information about
- the current state of a working copy
- in special sub-directories called <code>.svn</code>:
- </p>
+ <p>
+ It's very important that the working copies of different project do not overlap;
+ in particular,
+ we should never try to check out one project inside a working copy of another project.
+ The reason is that Subversion stories information about
+ the current state of a working copy
+ in special sub-directories called <code>.svn</code>:
+ </p>
<pre>
$ <span class="in">pwd</span>
-<span class="out">/home/vlad/monsters</span>
+<span class="out">/home/vlad/explore</span>
$ <span class="in">ls -a</span>
<span class="out">. .. .svn earth jupiter mars</span>
$ <span class="in">ls -F .svn</span>
<span class="out">entries prop-base/ props/ text-base/ tmp/</span>
</pre>
- <p class="continue">
- If two working copies overlap,
- the files in the <code>.svn</code> directories for one repository
- will be clobbered by the other repository's <code>.svn</code> files,
- and Subversion will become hopelessly confused.
- </p>
-
- </div>
-
- <p>
- Dracula can find out more about the history of the project
- using Subversion's <code>log</code> command:
+ <p class="continue">
+ If two working copies overlap,
+ the files in the <code>.svn</code> directories for one repository
+ will be clobbered by the other repository's <code>.svn</code> files,
+ and Subversion will become hopelessly confused.
</p>
+ </div>
+
+ <p>
+ Dracula can find out more about the history of the project
+ using Subversion's <code>log</code> command:
+ </p>
<pre>
$ <span class="in">svn log</span>
<span class="out">------------------------------------------------------------------------
r6 | mummy | 2010-07-26 09:21:10 -0400 (Mon, 26 Jul 2010) | 1 line
-Damn the budget---the Jovian moons would be a _perfect_ place for a lair.
+Damn the budget---the Jovian moons would be a _perfect_ place to explore.
------------------------------------------------------------------------
r5 | mummy | 2010-07-26 09:19:39 -0400 (Mon, 26 Jul 2010) | 1 line
-The budget might not even stretch to a deep-sea lair... :-(
+The budget might not even stretch to the Arctic :-(
------------------------------------------------------------------------
r4 | mummy | 2010-07-26 09:17:46 -0400 (Mon, 26 Jul 2010) | 1 line
-Budget cuts may force us to reconsider Earth as a base.
+Budget cuts may force us to do another dry run in the Arctic.
------------------------------------------------------------------------
r3 | mummy | 2010-07-26 09:14:14 -0400 (Mon, 26 Jul 2010) | 1 line
-Converting to wiki-formatted text.
+Converting document to wiki-formatted text.
------------------------------------------------------------------------
r2 | mummy | 2010-07-26 09:11:55 -0400 (Mon, 26 Jul 2010) | 1 line
-Hide near the face in Cydonia, perhaps?
+Or put it down near the Face of Cydonia?
------------------------------------------------------------------------
r1 | mummy | 2010-07-26 09:08:23 -0400 (Mon, 26 Jul 2010) | 1 line
-Thoughts on Mons Olympus (probably too obvious)
+Send the probe to Mons Olympus?
------------------------------------------------------------------------</span>
</pre>
- <p class="continue">
- Subversion displays a summary of all the changes made to the project so far.
- This list includes the
- <a href="glossary.html#revision-number">revision number</a>,
- the name of the person who made the change,
- the date the change was made,
- and whatever comment the user provided when the change was submitted.
- As we can see,
- the <code>monsters</code> project is currently at revision 6,
- and all changes so far have been made by the Mummy.
- </p>
-
- <p>
- Notice how detailed the comments on the updates are.
- Good comments are as important in version control as they are in coding.
- Without them, it can be very difficult to figure out who did what, when, and why.
- We can use comments like "Changed things" and "Fixed it" if we want,
- or even no comments at all,
- but we'll only be making more work for our future selves.
- </p>
-
- <p>
- Another thing to notice is that the revision number applies to the whole repository,
- not to a particular file.
- When we talk about "version 61" we mean
- "the state of all files and directories at that point."
- Older version control systems like CVS gave each file a new version number when it was updated,
- which meant that version 38 of one file could correspond in time to version 17 of another
- (<a href="#f:version_numbering">Figure XXX</a>).
- Experience shows that
- global version numbers that apply to everything in the repository
- are easier to manage than
- per-file version numbers,
- so that's what Subversion uses.
- </p>
+ <p class="continue">
+ Subversion displays a summary of all the changes made to the project so far.
+ This list includes the
+ <a href="glossary.html#revision-number">revision number</a>,
+ the name of the person who made the change,
+ the date the change was made,
+ and whatever comment the user provided when the change was submitted.
+ As we can see,
+ the <code>explore</code> project is currently at revision 6,
+ and all changes so far have been made by the Mummy.
+ </p>
+
+ <p>
+ Notice how detailed the comments on the updates are.
+ Good comments are as important in version control as they are in coding.
+ Without them, it can be very difficult to figure out who did what, when, and why.
+ We can use comments like "Changed things" and "Fixed it" if we want,
+ or even no comments at all,
+ but we'll only be making more work for our future selves.
+ </p>
+
+ <div class="box">
+ <h3>Numbering Versions</h3>
- <figure id="f:version_numbering">
- <img src="svn/version_numbering.png" alt="Version Numbering in CVS and Subversion" />
- </figure>
+ <p>
+ Another thing to notice is that the revision number applies to the whole repository,
+ not to a particular file.
+ When we talk about "version 61" we mean
+ "the state of all files and directories at that point."
+ Older version control systems like CVS gave each file a new version number when it was updated,
+ which meant that version 38 of one file could correspond in time to version 17 of another
+ (<a href="#f:version_numbering">Figure 7</a>).
+ Experience shows that
+ global version numbers that apply to everything in the repository
+ are easier to manage than
+ per-file version numbers,
+ so that's what Subversion uses.
+ </p>
- <p>
- A couple of cubicles away,
- Wolfman also runs <code>svn checkout</code>
- to get a working copy of the repository.
- He also gets version 6,
- so the files on his machine are the same as the files on Dracula's.
- While he is looking through the files,
- Dracula decides to add some information to the repository about Jupiter's moons.
- Using his favorite editor,
- he creates a file in the <code>jupiter</code> directory called <code>moons.txt</code>,
- and fills it with information about Io, Europa, Ganymede, and Callisto:
- </p>
+ <figure id="f:version_numbering">
+ <img src="svn/version_numbering.png" alt="Version Numbering Schemes" />
+ <figcaption>Figure 7: Version Numbering Schemes</figcaption>
+ </figure>
+ </div>
+
+ <p>
+ A couple of cubicles away,
+ Wolfman also runs <code>svn checkout</code>
+ to get a working copy of the repository.
+ He also gets version 6,
+ so the files on his machine are the same as the files on Dracula's.
+ While he is looking through the files,
+ Dracula decides to add some information to the repository about Jupiter's moons.
+ Using his favorite editor,
+ he creates a file in the <code>jupiter</code> directory called <code>moons.txt</code>,
+ and fills it with information about Io, Europa, Ganymede, and Callisto:
+ </p>
<pre src="svn/moons_initial.txt">
Name Orbital Radius Orbital Period Mass Radius
Calisto 1882.7 16.689018 1075.9 2410.3
</pre>
- After double-checking his data,
- he wants to commit the file to the repository so that everyone else on the project can see it.
- The first step is to add the file to his working copy using <code>svn add</code>:
- </p>
+ <p>
+ After double-checking his data,
+ he wants to commit the file to the repository so that everyone else on the project can see it.
+ The first step is to add the file to his working copy using <code>svn add</code>:
+ </p>
<pre>
$ <span class="in">svn add jupiter/moons.txt</span>
<span class="out">A jupiter/moons.txt</span>
</pre>
- Adding a file is not the same as creating it—he has already done that.
- Instead,
- the <code>svn add</code> command tells Subversion to add the file to
- the list of things it's supposed to manage.
- It's quite common,
- particularly in programming projects,
- to have backup files or intermediate files in a directory
- that aren't worth storing in the repository.
- This is why version control requires us to explicitly tell it which files are to be managed.
- </p>
-
- Once he has told Subversion to add the file,
- Dracula can go ahead and commit his changes to the repository.
- He uses the <code>-m</code> flag to provide a one-line message explaining what he's doing;
- if he didn't,
- Subversion would open his default editor
- so that he could type in something longer.
- </p>
+ <p>
+ Adding a file is not the same as creating it—he has already done that.
+ Instead,
+ the <code>svn add</code> command tells Subversion to add the file to
+ the list of things it's supposed to manage.
+ It's quite common,
+ particularly in programming projects,
+ to have backup files or intermediate files in a directory
+ that aren't worth storing in the repository.
+ This is why version control requires us to explicitly tell it which files are to be managed.
+ </p>
+
+ <p>
+ Once he has told Subversion to add the file,
+ Dracula can go ahead and commit his changes to the repository.
+ He uses the <code>-m</code> flag to provide a one-line message explaining what he's doing;
+ if he didn't,
+ Subversion would open his default editor
+ so that he could type in something longer.
+ </p>
<pre>
$ <span class="in">svn commit -m "Some basic facts about the Galilean moons of Jupiter." jupiter/moons.txt</span>
Committed revision 7.</span>
</pre>
- <p class="continue">
- When Dracula runs this command,
- Subversion establishes a connection to the server,
- copies over his changes,
- and updates the revision number from 6 to 7
- (<a href="#f:updated_repo">Figure XXX</a>).
- Again,
- this version number applies to the <em>whole</em> repository,
- not just to files that have changed.
- </p>
-
- <figure id="f:updated_repo">
- <img src="svn/updated_repo.png" alt="Updated Repository" />
- </figure>
-
- <p id="a:define-head">
- Back in his cubicle,
- Wolfman uses <code>svn update</code> to update his working copy.
- It tells him that a new file has been added
- and brings his working copy up to date with version 7 of the repository,
- because this is now the most recent revision
- (also called the <a href="glossary.html#head">head</a>).
- <code>svn update</code> updates an existing working copy,
- rather than checking out a new one.
- While <code>svn checkout</code> is usually only run once per project per machine,
- <code>svn update</code> may be run many times a day.
- </p>
-
- <p>
- Looking in the new file <code>jupiter/moons.txt</code>,
- Wolfman notices that Dracula has misspelled "Callisto"
- (it is supposed to have two L's.)
- Wolfman edits that line of the file:
- </p>
+ <p>
+ When Dracula runs the <code>svn commit</code> command,
+ Subversion establishes a connection to the server,
+ copies over his changes,
+ and updates the revision number from 6 to 7
+ (<a href="#f:updated_repo">Figure 8</a>).
+ </p>
+
+ <figure id="f:updated_repo">
+ <img src="svn/updated_repo.png" alt="Updated Repository" />
+ <figcaption>Figure 8: Updated Repository</figcaption>
+ </figure>
+
+ <p id="a:define-head">
+ Back in his cubicle,
+ Wolfman uses <code>svn update</code> to update his working copy.
+ It tells him that a new file has been added
+ and brings his working copy up to date with version 7 of the repository,
+ because this is now the most recent revision
+ (also called the <a href="glossary.html#head">head</a>).
+ <code>svn update</code> updates an existing working copy,
+ rather than checking out a new one.
+ While <code>svn checkout</code> is usually only run once per project per machine,
+ <code>svn update</code> may be run many times a day.
+ </p>
+
+ <p>
+ Looking in the new file <code>jupiter/moons.txt</code>,
+ Wolfman notices that Dracula has misspelled "Callisto"
+ (it is supposed to have two L's.)
+ Wolfman edits that line of the file:
+ </p>
<pre src="svn/moons_spelling.txt">
Name Orbital Radius Orbital Period Mass Radius
<span class="highlight">Callisto 1882.7 16.689018 1075.9 2410.3</span>
</pre>
- <p class="continue">
- He also adds a line about Amalthea,
- which he thinks might be a good site for a secret lair despite its small size:
- </p>
+ <p class="continue">
+ He also adds a line about Amalthea,
+ which he thinks might be an interesting place to send a probe
+ despite its small size:
+ </p>
<pre src="svn/moons_amalthea.txt">
Name Orbital Radius Orbital Period Mass Radius
Callisto 1882.7 16.689018 1075.9 2410.3
</pre>
- <p class="continue">
- uses the <code>svn status</code> command to check that he hasn't accidentally changed anything else:
- </p>
+ <p>
+ Next,
+ he uses the <code>svn status</code> command to check that he hasn't accidentally changed anything else:
+ </p>
<pre>
$ <span class="in">svn status</span>
<span class="out">M jupiter/moons.txt</span>
</pre>
- and then runs <code>svn commit</code>.
- Since has hasn't used the <code>-m</code> flag to provide a message on the command line,
- Subversion launches his default editor and shows him:
- </p>
+ <p class="continue">
+ and then runs <code>svn commit</code>.
+ Since has hasn't used the <code>-m</code> flag to provide a message on the command line,
+ Subversion launches his default editor and shows him:
+ </p>
<pre>
M jupiter/moons.txt
</pre>
- He changes this to be
- </p>
+ <p>
+ He changes this to be
+ </p>
<pre>
1. Fixed typo in moon's name: 'Calisto' -> 'Callisto'.
M jupiter/moons.txt
</pre>
- When he saves this temporary file and exits the editor,
- Subversion commits his changes:
- </p>
+ <p class="continue">
+ When he saves this temporary file and exits the editor,
+ Subversion commits his changes:
+ </p>
<pre>
<span class="out">Sending jupiter/moons.txt
Committed revision 8.</span>
</pre>
- Note that since Wolfman didn't specify a particular file to commit,
- Subversion commits <em>all</em> of his changes.
- This is why he ran the <code>svn status</code> command first.
- </p>
+ <p class="continue">
+ Note that since Wolfman didn't specify a particular file to commit,
+ Subversion commits <em>all</em> of his changes.
+ This is why he ran the <code>svn status</code> command first.
+ </p>
- <div class="box" id="b:basics:transaction">
+ <div class="box">
+ <h3>Which Editor?</h3>
+ <p>
+ If you don't have a default editor set up,
+ Subversion will probably open an editor called Vi.
+ If this happens,
+ type escape-colon-w-q-! to exit
+ and hope it never happens again.
+ </p>
+ </div>
- <h3>Working With Multiple Files</h3>
+ <div class="box" id="b:basics:transaction">
+ <h3>Working With Multiple Files</h3>
- Our example only includes one file,
- but version control can work on any number of files at once.
- For example,
- if Wolfman noticed that a dozen data files had the same incorrect header,
- he could change it in all 12 files,
- then commit all those changes at once.
- This is actually the best way to work:
- every logical change to the project should be a single commit,
- and every commit should include everything involved in one logical change.
- </p>
+ <p>
+ Our example only includes one file,
+ but version control can work on any number of files at once.
+ For example,
+ if Wolfman noticed that a dozen data files had the same incorrect header,
+ he could change it in all 12 files,
+ then commit all those changes at once.
+ This is actually the best way to work:
+ every logical change to the project should be a single commit,
+ and every commit should include everything involved in one logical change.
+ </p>
- </div>
-
- <p>
- That night,
- when Dracula rises from his coffin to start work,
- the first thing he wants to do is get Wolfman's changes.
- Before updating his working copy with <code>svn update</code>,
- though,
- he wants to see the differences between what he has
- and what he <em>will</em> have if he updates.
- To do this,
- Dracula uses <code>svn diff</code>.
- When run without arguments,
- it compares what's in his working copy to what he started with,
- and shows no differences:
- </p>
+ </div>
+
+ <p>
+ That night,
+ Dracula wants to synchronize with Wolfman's work.
+ Before updating his working copy with <code>svn update</code>,
+ though,
+ he checks to see if he has made any changes locally
+ by running <code>svn diff</code>.
+ Without arguments,
+ it compares what's in his working copy to what he got the last time he updated.
+ There are no differences,
+ so there's no output:
+ </p>
<pre>
$ <span class="in">svn diff</span>
$
</pre>
- To compare his working copy to the master,
- Dracula uses <code>svn diff -r HEAD</code>.
- The <code>-r</code> flag is used to specify a revision,
- while <code>HEAD</code> means
-
"<a href="#a:define-head">the latest version of the master</a>".
- </p>
+ <p class="continue">
+ To compare his working copy to the master,
+ Dracula uses <code>svn diff -r HEAD</code>.
+ The <code>-r</code> flag is used to specify a revision,
+ while <code>HEAD</code> means
+ "<a href="#a:define-head">the latest version of the master</a>".
+ </p>
<pre>
$ <span class="in">svn diff -r HEAD</span>
</span>
</pre>
- After looking over the changes,
- Dracula goes ahead and does the update.
- </p>
+ <p class="continue">
+ After looking over the changes,
+ Dracula goes ahead and does the update.
+ </p>
- <h3>Reading a Diff</h3>
+ <div class="box">
+ <h3>Reading a Diff</h3>
- <p>
- The output of <code>diff</code> isn't particularly user-friendly,
- but actually isn't that hard to figure out.
- The first two lines:
- </p>
+ <p>
+ The output of <code>diff</code> is cryptic even by Unix standards.
+ The first two lines:
+ </p>
<pre>
--- moons.txt(revision 9)
+++ moons.txt(working copy)
</pre>
- <p class="continue">
- signal that '-' will be used to show content from revision 9
- and '+' to show content from the user's working copy.
- The next line, with the '@' markers,
- indicates where lines were inserted or removed.
- This isn't really intended for human consumption:
- a variety of other software tools will use this information.
- </p>
-
- <p>
- The most important parts of what follows are the lines marked with '+' and '-',
- which show insertions and deletions respectively.
- Here,
- we can see that the line for Amalthea was inserted,
- and that the line for Callisto was changed
- (which is indicated by an add and a delete right next to one another).
- Many editors and other tools can display diffs like this in a two-column display,
- highlighting changes.
- </p>
-
- </div>
+ <p class="continue">
+ signal that '-' will be used to show content from revision 9
+ and '+' to show content from the user's working copy.
+ The next line, with the '@' markers,
+ indicates where lines were inserted or removed.
+ This isn't really intended for human consumption:
+ editors and other tools can use this information
+ to replay a series of edits against a file.
+ </p>
- <p>
- This is a very common workflow,
- and is the basic heartbeat of most developers' days.
- To recap,
- the steps are:
- </p>
+ <p>
+ The most important parts of what follows are the lines marked with '+' and '-',
+ which show insertions and deletions respectively.
+ Here,
+ we can see that the line for Amalthea was inserted,
+ and that the line for Callisto was changed
+ (which is indicated by an add and a delete right next to one another).
+ Many editors and other tools can display diffs like this in a two-column display,
+ highlighting changes.
+ </p>
- <ol>
+ </div>
- <li>
- Check to see if there are changes in the repository to download.
- </li>
+ <div class="box">
+ <h3>Diffing Other Files</h3>
- <li>
- Update our working copy with those changes.
- </li>
-
- <li>
- Do our own work.
- </li>
+ <p>
+ <code>svn diff</code> mimics the behavior of
+ the Unix <code>diff</code> command,
+ which can be used to compare any two files.
+ Given these two files:
+ </p>
- <li>
- Commit our changes to the repository so that other people can get them.
- </li>
+ <table>
+ <tr>
+ <th><code>left.txt</code></th>
+ <th><code>right.txt</code></th>
+ </tr>
+ <tr>
+ <td valign="top">
+<pre>hydrogen
+lithium
+sodium
+magnesium
+rubidium</pre>
+ </td>
+ <td valign="top">
+<pre>hydrogen
+lithium
+beryllium
+sodium
+potassium
+strontium</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p class="continue">
+ <code>diff</code>'s output is:
+ </p>
+<pre>
+$ <span class="in">diff left.txt right.txt</span>
+<span class="out">2a3
+> beryllium
+4,5c5,6
+< magnesium
+< rubidium
+---
+> potassium
+> strontium</span>
+</pre>
+ </div>
+
+ <p>
+ This is a very common workflow,
+ and is the basic heartbeat of most developers' days.
+ The steps are:
+ </p>
+
+ <ol>
+
+ <li>
+ Update our working copy
+ so that we have any changes other people have committed.
+ </li>
+
+ <li>
+ Do our own work.
+ </li>
+
+ <li>
+ Commit our changes to the repository
+ so that other people can get them.
+ </li>
+
+ </ol>
+
+ <p>
+ It's worth noticing here how important Wolfman's comments about his changes were.
+ It's hard to see the difference between "Calisto" with one 'L' and "Callisto" with two,
+ even if the line containing the difference has been highlighted.
+ Without Wolfman's comments,
+ Dracula might have wasted time wondering what the difference was.
+ </p>
+
+ <p>
+ In fact,
+ Wolfman should probably have committed his two changes separately,
+ since there's no logical connection between
+ fixing a typo in Callisto's name
+ and adding information about Amalthea to the same file.
+ Just as a function or program should do one job and one job only,
+ a single commit to version control should have a single logical purpose so that it's easier to find,
+ understand,
+ and if necessary undo later on.
+ </p>
+
+ <div class="keypoints">
+ <h3>Summary</h3>
+ <ul>
+ <li>Version control is a better way to manage shared files than email or shared folders.</li>
+ <li>The master copy is stored in a repository.</li>
+ <li>Nobody ever edits the master directory: instead, each person edits a local working copy.</li>
+ <li>People share changes by committing them to the master or updating their local copy from the master.</li>
+ <li>The version control system prevents people from overwriting each other's work by forcing them to merge concurrent changes before committing.</li>
+ <li>It also keeps a complete history of changes made to the master so that old versions can be recovered reliably.</li>
+ <li>Version control systems work best with text files, but can also handle binary files such as images and Word documents.</li>
+ <li>Every repository is identified by a URL.</li>
+ <li>Working copies of different repositories may not overlap.</li>
+ <li>Each changed to the master copy is identified by a unique revision number.</li>
+ <li>Revisions identify snapshots of the entire repository, not changes to individual files.</li>
+ <li>Each change should be commented to make the history more readable.</li>
+ <li>Commits are transactions: either all changes are successfully committed, or none are.</li>
+ <li>The basic workflow for version control is update-change-commit.</li>
+ <li><code>svn add <em>things</em></code> tells Subversion to start managing particular files or directories.</li>
+ <li><code>svn checkout <em>url</em></code> checks out a working copy of a repository.</li>
+ <li><code>svn commit -m "<em>message</em>" <em>things</em></code> sends changes to the repository.</li>
+ <li><code>svn diff</code> compares the current state of a working copy to the state after the most recent update.</li>
+ <li><code>svn diff -r HEAD</code> compares the current state of a working copy to the state of the master copy.</li>
+ <li><code>svn history</code> shows the history of a working copy.</li>
+ <li><code>svn status</code> shows the status of a working copy.</li>
+ <li><code>svn update</code> updates a working copy from the repository.</li>
+ </ul>
+ </div>
+
+ <div class="challenges">
+ <h3>Challenges</h3>
- </ol>
+ <ol>
- <p>
- It's worth noticing here how important Wolfman's comments about his changes were.
- It's hard to see the difference between "Calisto" with one 'L' and "Callisto" with two,
- even if the line containing the difference has been highlighted.
- Without Wolfman's comments,
- Dracula might have wasted time wondering what the difference was.
- </p>
+ <li>
+ Using the repository URL, user ID, and password provided by the instructor,
+ perform the following actions:
+ <ol>
+ <li>
+ Check out a working copy of the repository.
+ </li>
+ <li>
+ Create a text file called <em>your_id</em>.txt
+ (using your user ID instead of <em>your_id</em>)
+ and write a three-line biography of yourself in it.
+ </li>
+ <li>
+ Add this file to your working copy.
+ </li>
+ <li>
+ Commit your changes to the repository.
+ </li>
+ <li>
+ Update your working copy to get other people's biographies.
+ </li>
+ <li>
+ Examine the change log to see
+ the order in which people added their biographies
+ to the repository.
+ </li>
+ </ol>
+ </li>
- <p>
- In fact,
- Wolfman should probably have committed his two changes separately,
- since there's no logical connection between
- fixing a typo in Callisto's name
- and adding information about Amalthea to the same file.
- Just as a function or program should do one job and one job only,
- a single commit to version control should have a single logical purpose so that it's easier to find,
- understand,
- and if necessary undo later on.
- </p>
+ <li>
+ What does the command <code>svn diff -r 14</code> do?
+ What does it do if there have only been 10 changes to the repository?
+ </li>
- <div class="keypoints" id="k:basics">
- <h3>Summary</h3>
- <ul>
- <li>Version control is a better way to manage shared files than email or shared folders.</li>
- <li>The master copy is stored in a repository.</li>
- <li>Nobody ever edits the master directory: instead, each person edits a local working copy.</li>
- <li>People share changes by committing them to the master or updating their local copy from the master.</li>
- <li idea="paranoia">The version control system prevents people from overwriting each other's work by forcing them to merge concurrent changes before committing.</li>
- <li idea="perf">It also keeps a complete history of changes made to the master so that old versions can be recovered reliably.</li>
- <li>Version control systems work best with text files, but can also handle binary files such as images and Word documents.</li>
- <li>Every repository is identified by a URL.</li>
- <li>Working copies of different repositories may not overlap.</li>
- <li>Each changed to the master copy is identified by a unique revision number.</li>
- <li>Revisions identify snapshots of the entire repository, not changes to individual files.</li>
- <li idea="perf">Each change should be commented to make the history more readable.</li>
- <li>Commits are transactions: either all changes are successfully committed, or none are.</li>
- <li>The basic workflow for version control is update-change-commit.</li>
- <li><code>svn add <em>things</em></code> tells Subversion to start managing particular files or directories.</li>
- <li><code>svn checkout <em>url</em></code> checks out a working copy of a repository.</li>
- <li><code>svn commit -m "<em>message</em>" <em>things</em></code> sends changes to the repository.</li>
- <li><code>svn diff</code> compares the current state of a working copy to the state after the most recent update.</li>
- <li><code>svn diff -r HEAD</code> compares the current state of a working copy to the state of the master copy.</li>
- <li><code>svn history</code> shows the history of a working copy.</li>
- <li><code>svn status</code> shows the status of a working copy.</li>
- <li><code>svn update</code> updates a working copy from the repository.</li>
- </ul>
- </div>
+ <li>
+ By default,
+ Unix <code>diff</code> and <code>svn diff</code> compare files line by line.
+ Why doesn't this work for MP3 audio files?
+ </li>
- </section>
+ </ol>
+ </div>
- <section id="s:merge">
+</section>
- <h2>Merging Conflicts</h2>
+<section id="s:merge">
+ <h2>Merging Conflicts</h2>
- <div class="understand" id="u:merge">
- <h3>Understand:</h3>
- <ul>
- <li>What a conflict in an update is.</li>
- <li>How to resolve conflicts when updating.</li>
- </ul>
- </div>
+ <div class="understand">
+ <h3>Learning Objectives:</h3>
+ <ul>
+ <li>Explain what causes conflicts to occur and how to tell when one has occurred.</li>
+ <li>Resolve a conflict.</li>
+ <li>Identify the auxiliary files created when a conflict occurs.</li>
+ </ul>
+ </div>
- Dracula and Wolfman have both synchronized their working copies of <code>monsters</code>
- with version 8 of the repository.
- Dracula now edits his copy to change Amalthea's radius
- from a single number to a triple to reflect its irregular shape:
- </p>
+ <p>
+ Dracula and Wolfman have both synchronized their working copies of <code>explore</code>
+ with version 8 of the repository.
+ Dracula now edits his copy to change Amalthea's radius
+ from a single number to a triple to reflect its irregular shape:
+ </p>
<pre src="svn/moons_dracula_triple.txt">
Name Orbital Radius Orbital Period Mass Radius
Callisto 1882.7 16.689018 1075.9 2410.3
</pre>
- He then commits his work,
- creating revision 9 of the repository
- (<a href="#f:after_dracula_commits">Figure XXX</a>).
- </p>
+ <p class="continue">
+ He then commits his work,
+ creating revision 9 of the repository
+ (<a href="#f:after_dracula_commits">Figure 9</a>).
+ </p>
- <figure id="f:after_dracula_commits">
- <img src="svn/after_dracula_commits.png" alt="After Dracula Commits" />
- </figure>
+ <figure id="f:after_dracula_commits">
+ <img src="svn/after_dracula_commits.png" alt="After Dracula Commits" />
+ <figcaption>Figure 9: After Dracula Commits</figcaption>
+ </figure>
- But while he is doing this,
- Wolfman is editing <em>his</em> copy
- to add information about two other minor moons,
- Himalia and Elara:
- </p>
+ <p>
+ But while he is doing this,
+ Wolfman is editing <em>his</em> copy
+ to add information about two other minor moons,
+ Himalia and Elara:
+ </p>
<pre src="svn/moons_wolfman_extras.txt">
Name Orbital Radius Orbital Period Mass Radius
Elara 11740 259.6528 0.008 40.0</span>
</pre>
- When Wolfman tries to commit his changes to the repository,
- Subversion won't let him:
- </p>
+ <p>
+ When Wolfman tries to commit his changes to the repository,
+ Subversion won't let him:
+ </p>
<pre>
$ <span class="in">svn commit -m "Added data for Himalia, Elara"</span>
svn: resource out of date; try updating</span>
</pre>
- The reason is that
- Wolfman's changes were based on revision 8,
- but the repository is now at revision 9,
- and the file that Wolfman is trying to overwrite
- is different in the later revision.
- (Remember,
- one of version control's main jobs is to make sure that
- people don't trample on each other's work.)
- Wolfman has to update his working copy to get Dracula's changes before he can commit.
- Luckily,
- Dracula edited a line that Wolfman didn't change,
- so Subversion can merge the differences automatically.
- </p>
-
- This does <em>not</em> mean that Wolfman's changes have been committed to the repository:
- Subversion only does that when it's ordered to.
- Wolfman's changes are still in his working copy,
- and <em>only</em> in his working copy.
- But since Wolfman's version of the file now includes
- the lines that Dracula added,
- Wolfman can go ahead and commit them as usual to create revision 10.
- </p>
-
- Wolfman's working copy is now in sync with the master,
- but Dracula's is one behind at revision 9.
- At this point,
- they independently decide to add measurement units
- to the columns in <code>moons.txt</code>.
- Wolfman is quicker off the mark this time;
- he adds a line to the file:
- </p>
+ <p class="continue">
+ The reason is that
+ Wolfman's changes were based on revision 8,
+ but the repository is now at revision 9,
+ and the file that Wolfman is trying to overwrite
+ is different in the later revision.
+ (Remember,
+ one of version control's main jobs is to make sure that
+ people don't trample on each other's work.)
+ Wolfman has to update his working copy to get Dracula's changes before he can commit.
+ Luckily,
+ Dracula edited a line that Wolfman didn't change,
+ so Subversion can merge the differences automatically.
+ </p>
+
+ <p>
+ This does <em>not</em> mean that Wolfman's changes have been committed to the repository:
+ Subversion only does that when it's ordered to.
+ Wolfman's changes are still in his working copy,
+ and <em>only</em> in his working copy.
+ But since Wolfman's version of the file now includes
+ the lines that Dracula added,
+ Wolfman can go ahead and commit them as usual to create revision 10.
+ </p>
+
+ <p>
+ Wolfman's working copy is now in sync with the master,
+ but Dracula's is one behind at revision 9.
+ At this point,
+ they independently decide to add measurement units
+ to the columns in <code>moons.txt</code>.
+ Wolfman is quicker off the mark this time;
+ he adds a line to the file:
+ </p>
<pre src="svn/moons_wolfman_units.txt">
Name Orbital Radius Orbital Period Mass Radius
Elara 11740 259.6528 0.008 40.0
</pre>
- and commits it to create revision 11.
- While he is doing this,
- though,
- Dracula inserts a different line at the top of the file:
- </p>
+ <p class="continue">
+ and commits it to create revision 11.
+ While he is doing this,
+ though,
+ Dracula inserts a different line at the top of the file:
+ </p>
<pre src="svn/moons_dracula_units.txt">
Name Orbital Radius Orbital Period Mass Radius
Elara 11740 259.6528 0.008 40.0
</pre>
- Once again,
- when Dracula tries to commit,
- Subversion tells him he can't.
- But this time,
- when Dracula does updates his working copy,
- he doesn't just get the line Wolfman added to create revision 11.
- There is an actual conflict in the file,
- so Subversion asks Dracula what he wants to do:
- </p>
+ <p>
+ Once again,
+ when Dracula tries to commit,
+ Subversion tells him he can't.
+ But this time,
+ when Dracula does updates his working copy,
+ he doesn't just get the line Wolfman added to create revision 11.
+ There is an actual conflict in the file,
+ so Subversion asks Dracula what he wants to do:
+ </p>
<pre src="svn/moons_dracula_conflict.txt">
$ <span class="in">svn update</span>
(s) show all options:</span>
</pre>
- Dracula choose <code>p</code> for "postpone",
- which tells Subversion that he'll deal with the problem later.
- Once the update is finished,
- he opens <code>moons.txt</code> in his editor and sees:
- </p>
+ <p>
+ Dracula choose <code>p</code> for "postpone",
+ which tells Subversion that he'll deal with the problem later.
+ Once the update is finished,
+ he opens <code>moons.txt</code> in his editor and sees:
+ </p>
<pre>
Name Orbital Radius Orbital Period Mass
Callisto 1882.7 16.689018 1075.9
</pre>
- As we can see,
- Subversion has inserted
-
<a href="glossary.html#conflict-marker">conflict markers</a>
- in <code>moons.txt</code>
- wherever there is a conflict.
- The line <code><<<<<<< .mine</code> shows the start of the conflict,
- and is followed by the lines from the local copy of the file.
- The separator <code>=======</code> is then
- followed by the lines from the repository's file that are in conflict with that section,
- while <code>>>>>>>> .r11</code> marks the end of the conflict.
- </p>
-
- Before he can commit,
- Dracula has to edit his copy of the file to get rid of those markers.
- He changes it to:
- </p>
+ <p class="continue">
+ As we can see,
+ Subversion has inserted
+ <a href="glossary.html#conflict-marker">conflict markers</a>
+ in <code>moons.txt</code>
+ wherever there is a conflict.
+ The line <code><<<<<<< .mine</code> shows the start of the conflict,
+ and is followed by the lines from the local copy of the file.
+ The separator <code>=======</code> is then
+ followed by the lines from the repository's file that are in conflict with that section,
+ while <code>>>>>>>> .r11</code> marks the end of the conflict.
+ </p>
+
+ <p>
+ Before he can commit,
+ Dracula has to edit his copy of the file to get rid of those markers.
+ He changes it to:
+ </p>
<pre src="svn/moons_dracula_resolved.txt">
Name Orbital Radius Orbital Period Mass Radius
Elara 11740 259.6528 0.008 40.0
</pre>
- <p class="continue">
- then uses the <code>svn resolved</code> command to tell Subversion that
- he has fixed the problem.
- Subversion will now let him commit to create revision 12.
- </p>
-
- <div class="box">
-
- <h3>Auxiliary Files</h3>
+ <p class="continue">
+ then uses the <code>svn resolved</code> command to tell Subversion that
+ he has fixed the problem.
+ Subversion will now let him commit to create revision 12.
+ </p>
- <p>
- When Dracula did his update and Subversion detected the conflict in <code>moons.txt</code>,
- it created three temporary files to help Dracula resolve it.
- The first is called <code>moons.txt.r9</code>;
- it is the file as it was in Dracula's local copy
- before he started making changes,
- i.e., the common ancestor for his work
- and whatever he is in conflict with.
- </p>
+ <div class="box">
+ <h3>Auxiliary Files</h3>
- <p>
- The second file is <code>moons.txt.r11</code>.
- This is the most up-to-date revision from the repository—the
- file as it is including Wolfman's changes.
- The third temporary file, <code>moons.txt.mine</code>,
- is the file as it was in Dracula's working copy before he did the Subversion update.
- </p>
+ <p>
+ When Dracula did his update and Subversion detected the conflict in <code>moons.txt</code>,
+ it created three temporary files to help Dracula resolve it.
+ The first is called <code>moons.txt.r9</code>;
+ it is the file as it was in Dracula's local copy
+ before he started making changes,
+ i.e., the common ancestor for his work
+ and whatever he is in conflict with.
+ </p>
- <p>
- Subversion creates these auxiliary files primarily
- to help people merge conflicts in binary files.
- It wouldn't make sense to insert <code><<<<<<<</code>
- and <code>>>>>>>></code> characters into an image file
- (it would almost certainly result in a corrupted image).
- The <code>svn resolved</code> command deletes these three extra files
- as well as telling Subversion that the conflict has been taken care of.
- </p>
+ <p>
+ The second file is <code>moons.txt.r11</code>.
+ This is the most up-to-date revision from the repository—the
+ file as it is including Wolfman's changes.
+ The third temporary file, <code>moons.txt.mine</code>,
+ is the file as it was in Dracula's working copy before he did the Subversion update.
+ </p>
- </div>
+ <p>
+ Subversion creates these auxiliary files primarily
+ to help people merge conflicts in binary files.
+ It wouldn't make sense to insert <code><<<<<<<</code>
+ and <code>>>>>>>></code> characters into an image file
+ (it would almost certainly result in a corrupted image).
+ The <code>svn resolved</code> command deletes these three extra files
+ as well as telling Subversion that the conflict has been taken care of.
+ </p>
- <p>
- Some power users prefer to work with interpolated conflict markers directly,
- but for the rest of us,
- there are several tools for displaying differences and helping to merge them,
- including <a href="http://diffuse.sourceforge.net/">Diffuse</a> and <a href="http://winmerge.org/">WinMerge</a>.
- If Dracula launches Diffuse,
- it displays his file,
- the common base that he and Wolfman were working from,
- and Wolfman's file in a three-pane view
- (<a href="#f:diff_viewer">Figure XXX</a>):
- </p>
+ </div>
+
+ <p>
+ Some power users prefer to work with interpolated conflict markers directly,
+ but for the rest of us,
+ there are several tools for displaying differences and helping to merge them,
+ including <a href="http://diffuse.sourceforge.net/">Diffuse</a> and <a href="http://winmerge.org/">WinMerge</a>.
+ If Dracula launches Diffuse,
+ it displays his file,
+ the common base that he and Wolfman were working from,
+ and Wolfman's file in a three-pane view
+ (<a href="#f:diff_viewer">Figure 10</a>):
+ </p>
+
+ <figure id="f:diff_viewer">
+ <img src="svn/diff_viewer.png" alt="A Difference Viewer" />
+ <figcaption>Figure 10: A Difference Viewer</figcaption>
+ </figure>
+
+ <p class="continue">
+ Dracula can use the buttons to merge changes from either of the edited versions
+ into the common ancestor,
+ or edit the central pane directly.
+ Again,
+ once he is done,
+ he uses <code>svn resolved</code> and <code>svn commit</code>
+ to create revision 12 of the repository.
+ </p>
+
+ <p>
+ In this case, the conflict was small and easy to fix.
+ However, if two or more people on a team are repeatedly creating conflicts for one another,
+ it's usually a signal of deeper communication problems:
+ either they aren't talking as often as they should, or their responsibilities overlap.
+ If used properly,
+ the version control system can help the team find and fix these issues
+ so that it will be more productive in future.
+ </p>
+
+ <div class="box">
+ <h3>Working With Multiple Files</h3>
- <figure id="f:diff_viewer">
- <img src="svn/diff_viewer.png" alt="A Difference Viewer" />
- </figure>
+ <p>
+ As mentioned <a href="#a:transaction">earlier</a>,
+ every logical change to a project should result in a single commit,
+ and every commit should represent one logical change.
+ This is especially true when resolving conflicts:
+ the work done to reconcile one person's changes with another are often complicated,
+ so it should be a single entry in the project's history,
+ with other, later, changes coming after it.
+ </p>
- <p class="continue">
- Dracula can use the buttons to merge changes from either of the edited versions
- into the common ancestor,
- or edit the central pane directly.
- Again,
- once he is done,
- he uses <code>svn resolved</code> and <code>svn commit</code>
- to create revision 12 of the repository.
- </p>
+ </div>
- <p>
- In this case, the conflict was small and easy to fix.
- However, if two or more people on a team are repeatedly creating conflicts for one another,
- it's usually a signal of deeper communication problems:
- either they aren't talking as often as they should, or their responsibilities overlap.
- If used properly,
- the version control system can help the team find and fix these issues
- so that it will be more productive in future.
- </p>
+ <div class="keypoints">
+ <h3>Summary</h3>
+ <ul>
+ <li>Conflicts must be resolved before a commit can be completed.</li>
+ <li>Subversion puts markers in text files to show regions of conflict.</li>
+ <li>For each conflicted file, Subversion creates auxiliary files containing the common parent, the master version, and the local version.</li>
+ <li><code>svn resolve <em>files</em></code> tells Subversion that conflicts have been resolved.</li>
+ </ul>
+ </div>
- <div class="box">
+ <div class="challenges">
+ <h3>Challenges</h3>
- <h3>Working With Multiple Files</h3>
+ <p>
+ If you are working in a group,
+ partner with someone who has also wrote a biography for themselves
+ for the previous section's challenges.
+ </p>
- <p>
- As mentioned <a href="#a:transaction">earlier</a>,
- every logical change to a project should result in a single commit,
- and every commit should represent one logical change.
- This is especially true when resolving conflicts:
- the work done to reconcile one person's changes with another are often complicated,
- so it should be a single entry in the project's history,
- with other, later, changes coming after it.
- </p>
+ <ol>
+ <li>
+ Both partners use <code>svn update</code>
+ to make sure their working copies are up to date
+ and that there are no local changes.
+ </li>
+ <li>
+ The first partner edits her biography and commits the changes.
+ </li>
+ <li>
+ The second partner edits her copy of the file
+ (<em>without</em> having updated to get the first partner's changes),
+ then tries to <code>svn commit</code>.
+ </li>
+ <li>
+ Once the second partner has resolved the conflict,
+ she commits her changes.
+ </li>
+ <li>
+ Repeat these four steps with roles reversed.
+ </li>
+ </ol>
- </div>
+ <p>
+ If you are working on your own,
+ you can simulate the steps above
+ by checking out a second copy of the project into a new directory.
+ (Remember,
+ this cannot overlap any existing checked-out copies.)
+ Edit your biography in one copy and commit those changes,
+ then switch to the other copy and edit the same file
+ before updating.
+ <a href="#f:challenge_conflict">Figure 11</a> shows
+ the differences between these two challenges.
+ </p>
- <div class="keypoints" id="k:merge">
- <h3>Summary</h3>
- <ul>
- <li>Conflicts must be resolved before a commit can be completed.</li>
- <li>Subversion puts markers in text files to show regions of conflict.</li>
- <li>For each conflicted file, Subversion creates auxiliary files containing the common parent, the master version, and the local version.</li>
- <li><code>svn resolve <em>files</em></code> tells Subversion that conflicts have been resolved.</li>
- </ul>
- </div>
+ <figure id="f:challenge_conflict">
+ <img src="svn/challenge_conflict.png" alt="Practicing Conflict Resolution" />
+ <figcaption>Figure 11: Practicing Conflict Resolution</figcaption>
+ </figure>
+ </div>
- </section>
+</section>
<section id="s:rollback">
Now that we have seen how to merge files and resolve conflicts,
we can look at how to use version control as an "infinite undo".
Suppose that when Wolfman starts work late one night,
- his copy of <code>monsters</code> is in sync with the head at revision 12.
+ his copy of <code>explore</code> is in sync with the head at revision 12.
He decides to edit the file <code>moons.txt</code>;
unfortunately, he forgot that there was a full moon,
so his changes don't make a lot of sense:
</section>
- <section id="s:summary">
-
- <h2>Summing Up</h2>
-
- <p>
- Correlation does not imply causality,
- but there is a very strong correlation between
- using version control
- and doing good computational science.
- There's an equally strong correlation
- between <em>not</em> using it and wasting effort,
- so today (the middle of 2012),
- I will not review a paper if the software used in it
- is not under version control.
- Its authors' work might be interesting,
- but without the kind of record-keeping that version control provides,
- there's no way to know exactly what they did and when.
- Just as importantly,
- if someone doesn't know enough about computing to use version control,
- the odds are good that they don't know enough
- to do the programming right either.
- </p>
-
- </section>
+<section id="s:summary">
+ <h2>Summing Up</h2>
+
+ <p>
+ Correlation does not imply causality,
+ but there is a very strong correlation between
+ using version control
+ and doing good computational science.
+ There's an equally strong correlation
+ between <em>not</em> using it and either wasting effort or getting things wrong.
+ Today (the middle of 2013),
+ I will not review a paper if the software used in it
+ is not under version control.
+ The work it reports might be interesting,
+ but without the kind of record-keeping that version control provides,
+ there's no way to know exactly what its authors did.
+ Just as importantly,
+ if someone doesn't know enough about computing to use version control,
+ the odds are good that they don't know enough
+ to do the programming right either.
+ </p>
+
+</section>
{% endblock content %}
projects / swc-version-control-svn.git / blobdiff