From: Greg Wilson Date: Sat, 20 Apr 2013 15:30:01 +0000 (-0400) Subject: Starting to revise instructors' guide on SVN X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=af2312ba8b4d48309bfeac51fb4d10f8652eaf06;p=swc-boot-camp.git Starting to revise instructors' guide on SVN --- diff --git a/svn.html b/svn.html index 755e223..fe01b5f 100644 --- a/svn.html +++ b/svn.html @@ -5,240 +5,260 @@ {% endblock file_metadata %} {% block content %} -
    -
  1. Basic Use
    2. -
  2. Merging Conflicts
    3. -
  3. Recovering Old Versions
    4. -
  4. Setting up a Repository
    5. -
  5. Provenance
    6. -
  6. Summing Up
    7. -
+
    +
  1. Basic Use
    2. +
  2. Merging Conflicts
    3. +
  3. Recovering Old Versions
    4. +
  4. Setting up a Repository
    5. +
  5. Provenance
    6. +
  6. Summing Up
    7. +
+ +

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

+ +

+ The right solution is to use a + version control system + to manage their work. + Version control is better than mailing files back and forth because: +

+ +
    + +
  1. + It's hard (but not impossible) to accidentally overlook or overwrite someone's changes, + because the version control system highlights them automatically. +
    2. + +
  2. + 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). +
    3. + +
  3. + 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. +
    4. + +
+ +
+

Nothing's Perfekt

+ +

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

+
+ +

+ The rest of this chapter will explore how to use + a popular open source version control system called Subversion. +

+ +
+

For Instructors

+ +

explain

+ +
+

Prerequisites

+

prereq

+
+ +
+

Teaching Notes

+
    +
+
+ +
+ +
+

Basic Use

+ +
+

Learning Objectives:

+
    +
  • Where version control stores information.
    • +
  • How to check out a working copy of a repository.
    • +
  • How to view the history of changes to a project.
    • +
  • Why working copies of different projects should not overlap.
    • +
  • How to add files to a project.
    • +
  • How to submit changes made locally to a project's master copy.
    • +
  • How to update a working copy to get changes made to the master.
    • +
  • How to check the status of a working copy.
    • +
+
+ +

+ A version control system keeps the master copy of a file + in a repository + located on a server—a computer + that is never used directly by people, + but only by their programs + (Figure 1). + No-one ever edits the master copy directly. + Instead, + Wolfman and Dracula each have a working copy + on their own machines. + They can each edit their working copies whenever and however they want. +

+ +
+ Repositories and Working Copies +
Figure 1: Repositories and Working Copies
+
+ +

+ When Wolfman is ready to share his changes with Dracula, + he commits his work to the repository + (Figure 2). + Dracula can then update 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. +

+ +
+ Sharing Files Through Version Control +
Figure 2: Sharing Files Through Version Control
+
+ +

+ 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 + (Figure 3): +

+ +
+ Wolfman Commits First +
Figure 3: Wolfman Commits First
+
+ +

+ If Dracula now tries to commit something that would overwrite Wolfman's changes + the version control system detects the conflict, + halts the commit, + and tells Dracula that there's a problem + (Figure 4): +

+ +
+ Dracula Has a Conflict +
Figure 4: Dracula Has a Conflict
+
+ +

+ Dracula must resolve 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 + (Figure 5). + 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. +

+ +
+ Resolving the Conflict +
Figure 5: Resolving the Conflict
+
+ +
+

Forgiveness vs. Permission

- 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 locking the master copy + whenever someone was working on it. + This pessimistic 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.

- The right solution is to use a version control system - to manage their work. - Version control is better than mailing files back and forth because: + Most of today's version control systems use + an optimistic 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.

+
-
    +

    + 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 https://universal.software-carpentry.org/monsters. + Every repository has an address like this that uniquely identifies the location of the master copy. +

    -
  1. - It's hard (but not impossible) to accidentally overlook or overwrite someone's changes, - because the version control system highlights them automatically. -
    2. - -
  2. - There are no arguments about whose copy is the most up to date. -
    3. - -
  3. - 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. -
    4. - -
+
+

There's More Than One Way To Do It

- 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. + 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 reference for links.

- -

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

- -
- -

Basic Use

- -
-

Understand:

-
    -
  • Where version control stores information.
    • -
  • How to check out a working copy of a repository.
    • -
  • How to view the history of changes to a project.
    • -
  • Why working copies of different projects should not overlap.
    • -
  • How to add files to a project.
    • -
  • How to submit changes made locally to a project's master copy.
    • -
  • How to update a working copy to get changes made to the master.
    • -
  • How to check the status of a working copy.
    • -
-
- -

- A version control system keeps the master copy of a file - in a repository - located on a server—a computer - that is never used directly by people, - but only by their programs - (Figure XXX). - No-one ever edits the master copy directly. - Instead, - Wolfman and Dracula each have a working copy - on their own computer. - This lets them make whatever changes they want whenever they want. -

- -
- A Version Control Repository -
- -

- As soon Wolfman is ready to share his changes, - he commits his work to the repository - (Figure XXX). - Dracula can then update his working copy to get those changes. - And of course, - when Dracula finishes working on something, - he can commit and then Wolfman can update. -

- -
- Version Control Workflow -
- -

- 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 locking the master copy - whenever someone was working on it. - This pessimistic 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. -

- -

- Most of today's version control systems use - an optimistic 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 does happen, - the version control system helps people reconcile their changes. -

- -

- 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 - (Figure XXX): -

- -
- Wolfman Commits First -
- -

- If Dracula now tries to commit something that would overwrite Wolfman's changes - the version control system stops him - and points out the conflict - (Figure XXX): -

- -
- Dracula Has a Conflict -
- -

- Dracula must resolve 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. -

- -

- 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 universal.software-carpentry.org server. - The full URL for this repository is https://universal.software-carpentry.org/monsters. - Every repository has an address like this that uniquely identifies the location of the master copy. -

- -

- It's Monday night. - In order to get a working copy on his computer, - Dracula has to check out 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: -

- -
-

There's More Than One Way To Do It

- -

- 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: -

- -
    - -
  • - TortoiseSVN - is integrated into the Windows desktop, - so there's no separate GUI as such. -
    • - -
  • - RapidSVN is free, - and runs on many platforms, - but some users report difficulties installing it. -
    • - -
  • - Syntevo's SmartSVN isn't free, - but it costs less than most textbooks, - and is more stable (and has a friendlier interface) than RapidSVN. -
    • - -
- -
- -

- While in his home directory, - Dracula types the command: -

+
+ +

+ It's Monday morning, + and Dracula has just joined the project. + In order to get a working copy on his computer, + Dracula has to check out 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. +

+ +

+ While in his home directory, + Dracula types the command: + 

 $ svn checkout https://universal.software-carpentry.org/monsters
-

- This creates a new directory called monsters - and fills it with a copy of the repository's contents - (Figure XXX). -

+

+ This creates a new directory called monsters + and fills it with a copy of the repository's contents + (Figure 6). + 

 A    monsters/jupiter
@@ -252,14 +272,15 @@ A    monsters/earth/carlsbad.txt
 Checked out revision 6.
-
- Example Repository -
+
+ Example Repository +
Figure 6: Example Repository
+
-

- Dracula can then go into this directory - and use regular shell commands to view the files: -

+

+ Dracula can then go into this directory + and use regular shell commands to view the files: + 

 $ cd monsters
@@ -275,18 +296,17 @@ mars:
 cydonia.txt  mons-olympus.txt
-
- -

Don't Let the Working Copies Overlap

+
+

Don't Let the Working Copies Overlap

-

- 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 .svn: -

+

+ 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 .svn: + 

 $ pwd
@@ -297,101 +317,105 @@ $ ls -F .svn
 entries    prop-base/    props/    text-base/    tmp/
-

- If two working copies overlap, - the files in the .svn directories for one repository - will be clobbered by the other repository's .svn files, - and Subversion will become hopelessly confused. -

- -
- -

- Dracula can find out more about the history of the project - using Subversion's log command: +

+ If two working copies overlap, + the files in the .svn directories for one repository + will be clobbered by the other repository's .svn files, + and Subversion will become hopelessly confused.

+
+ +

+ Dracula can find out more about the history of the project + using Subversion's log command: + 

 $ svn log
 ------------------------------------------------------------------------
 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?
 ------------------------------------------------------------------------
-

- Subversion displays a summary of all the changes made to the project so far. - This list includes the - revision number, - 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 monsters project is currently at revision 6, - and all changes so far have been made by the Mummy. -

- -

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

+

+ Subversion displays a summary of all the changes made to the project so far. + This list includes the + revision number, + 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 monsters project is currently at revision 6, + and all changes so far have been made by the Mummy. +

+ +

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

+ +
+

Numbering Versions

-

- 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 - (Figure XXX). - 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. -

- -
- Version Numbering in CVS and Subversion -
+

+ 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 + (Figure 7). + 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. +

-

- A couple of cubicles away, - Wolfman also runs svn checkout - 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 jupiter directory called moons.txt, - and fills it with information about Io, Europa, Ganymede, and Callisto: -

+
+ Version Numbering Schemes +
Figure 7: Version Numbering Schemes
+
+
+ +

+ A couple of cubicles away, + Wolfman also runs svn checkout + 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 jupiter directory called moons.txt, + and fills it with information about Io, Europa, Ganymede, and Callisto: + 

 Name            Orbital Radius  Orbital Period  Mass            Radius
@@ -401,37 +425,37 @@ Ganymede        1070.4          7.154553        1481.9          2631.2
 Calisto         1882.7          16.689018       1075.9          2410.3
-

- 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 svn add: -

+

+ 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 svn add: + 

 $ svn add jupiter/moons.txt
 A         jupiter/moons.txt
-

- Adding a file is not the same as creating it—he has already done that. - Instead, - the svn add 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. -

- -

- Once he has told Subversion to add the file, - Dracula can go ahead and commit his changes to the repository. - He uses the -m 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. -

+

+ Adding a file is not the same as creating it—he has already done that. + Instead, + the svn add 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. +

+ +

+ Once he has told Subversion to add the file, + Dracula can go ahead and commit his changes to the repository. + He uses the -m 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. + 

 $ svn commit -m "Some basic facts about the Galilean moons of Jupiter." jupiter/moons.txt
@@ -440,40 +464,38 @@ Transmitting file data .
 Committed revision 7.
-

- 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 - (Figure XXX). - Again, - this version number applies to the whole repository, - not just to files that have changed. -

- -
- Updated Repository -
- -

- Back in his cubicle, - Wolfman uses svn update 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 head). - svn update updates an existing working copy, - rather than checking out a new one. - While svn checkout is usually only run once per project per machine, - svn update may be run many times a day. -

- -

- Looking in the new file jupiter/moons.txt, - Wolfman notices that Dracula has misspelled "Callisto" - (it is supposed to have two L's.) - Wolfman edits that line of the file: -

+

+ When Dracula runs the svn commit command, + Subversion establishes a connection to the server, + copies over his changes, + and updates the revision number from 6 to 7 + (Figure 8). +

+ +
+ Updated Repository +
Figure 8: Updated Repository
+
+ +

+ Back in his cubicle, + Wolfman uses svn update 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 head). + svn update updates an existing working copy, + rather than checking out a new one. + While svn checkout is usually only run once per project per machine, + svn update may be run many times a day. +

+ +

+ Looking in the new file jupiter/moons.txt, + Wolfman notices that Dracula has misspelled "Callisto" + (it is supposed to have two L's.) + Wolfman edits that line of the file: + 

 Name            Orbital Radius  Orbital Period  Mass            Radius
@@ -483,10 +505,11 @@ Ganymede        1070.4          7.154553        1481.9          2631.2
 Callisto        1882.7          16.689018       1075.9          2410.3
-

- He also adds a line about Amalthea, - which he thinks might be a good site for a secret lair despite its small size: -

+

+ He also adds a line about Amalthea, + which he thinks might be an interesting place to send a probe + despite its small size: + 

 Name            Orbital Radius  Orbital Period  Mass            Radius
@@ -497,20 +520,21 @@ Ganymede        1070.4          7.154553        1481.9          2631.2
 Callisto        1882.7          16.689018       1075.9          2410.3
-

- uses the svn status command to check that he hasn't accidentally changed anything else: -

+

+ Next, + he uses the svn status command to check that he hasn't accidentally changed anything else: + 

 $ svn status
 M       jupiter/moons.txt
-

- and then runs svn commit. - Since has hasn't used the -m flag to provide a message on the command line, - Subversion launches his default editor and shows him: -

+

+ and then runs svn commit. + Since has hasn't used the -m flag to provide a message on the command line, + Subversion launches his default editor and shows him: + 

 
@@ -519,9 +543,9 @@ $ svn status
 M    jupiter/moons.txt
-

- He changes this to be -

+

+ He changes this to be + 

 1. Fixed typo in moon's name: 'Calisto' -> 'Callisto'.
@@ -531,10 +555,10 @@ M    jupiter/moons.txt
 M    jupiter/moons.txt
-

- When he saves this temporary file and exits the editor, - Subversion commits his changes: -

+

+ When he saves this temporary file and exits the editor, + Subversion commits his changes: + 

 Sending        jupiter/moons.txt
@@ -542,57 +566,65 @@ Transmitting file data .
 Committed revision 8.
-

- Note that since Wolfman didn't specify a particular file to commit, - Subversion commits all of his changes. - This is why he ran the svn status command first. -

- -
+

+ Note that since Wolfman didn't specify a particular file to commit, + Subversion commits all of his changes. + This is why he ran the svn status command first. +

-

Working With Multiple Files

+
+

Which Editor?

+

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

+
-

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

+
+

Working With Multiple Files

-
+

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

-

- 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 svn update, - though, - he wants to see the differences between what he has - and what he will have if he updates. - To do this, - Dracula uses svn diff. - When run without arguments, - it compares what's in his working copy to what he started with, - and shows no differences: -

+
+ +

+ That night, + Dracula wants to synchronize with Wolfman's work. + Before updating his working copy with svn update, + though, + he checks to see if he has made any changes locally + by running svn diff. + 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: + 

 $ svn diff
 $
-

- To compare his working copy to the master, - Dracula uses svn diff -r HEAD. - The -r flag is used to specify a revision, - while HEAD means - "the latest version of the master". -

+

+ To compare his working copy to the master, + Dracula uses svn diff -r HEAD. + The -r flag is used to specify a revision, + while HEAD means + "the latest version of the master". + 

 $ svn diff -r HEAD
@@ -609,123 +641,136 @@ $ svn diff -r HEAD
-

- After looking over the changes, - Dracula goes ahead and does the update. -

+

+ After looking over the changes, + Dracula goes ahead and does the update. +

-
-

Reading a Diff

+
+

Reading a Diff

-

- The output of diff isn't particularly user-friendly, - but actually isn't that hard to figure out. - The first two lines: -

+

+ The output of diff is cryptic even by Unix standards. + The first two lines: + 

 --- moons.txt(revision 9)
 +++ moons.txt(working copy)
-

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

- -

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

- -
- -

- This is a very common workflow, - and is the basic heartbeat of most developers' days. - To recap, - the steps are: -

- -
    - -
  1. - Check to see if there are changes in the repository to download. -
    2. - -
  2. - Update our working copy with those changes. -
    3. +

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

    -
  3. - Do our own work. -
    4. +

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

    -
  4. - Commit our changes to the repository so that other people can get them. -
    5. +
+ +

+ This is a very common workflow, + and is the basic heartbeat of most developers' days. + The steps are: +

+ +
    + +
  1. + Update our working copy + so that we have any changes other people have committed. +
    2. + +
  2. + Do our own work. +
    3. + +
  3. + Commit our changes to the repository + so that other people can get them. +
    4. + +
+ +

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

+ +

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

+ +
+

Summary

+
    +
  • Version control is a better way to manage shared files than email or shared folders.
    • +
  • The master copy is stored in a repository.
    • +
  • Nobody ever edits the master directory: instead, each person edits a local working copy.
    • +
  • People share changes by committing them to the master or updating their local copy from the master.
    • +
  • The version control system prevents people from overwriting each other's work by forcing them to merge concurrent changes before committing.
    • +
  • It also keeps a complete history of changes made to the master so that old versions can be recovered reliably.
    • +
  • Version control systems work best with text files, but can also handle binary files such as images and Word documents.
    • +
  • Every repository is identified by a URL.
    • +
  • Working copies of different repositories may not overlap.
    • +
  • Each changed to the master copy is identified by a unique revision number.
    • +
  • Revisions identify snapshots of the entire repository, not changes to individual files.
    • +
  • Each change should be commented to make the history more readable.
    • +
  • Commits are transactions: either all changes are successfully committed, or none are.
    • +
  • The basic workflow for version control is update-change-commit.
    • +
  • svn add things tells Subversion to start managing particular files or directories.
    • +
  • svn checkout url checks out a working copy of a repository.
    • +
  • svn commit -m "message" things sends changes to the repository.
    • +
  • svn diff compares the current state of a working copy to the state after the most recent update.
    • +
  • svn diff -r HEAD compares the current state of a working copy to the state of the master copy.
    • +
  • svn history shows the history of a working copy.
    • +
  • svn status shows the status of a working copy.
    • +
  • svn update updates a working copy from the repository.
    • +
+
+ +
+

Challenges

+
    -
+
  • +
    • -

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

    +
  • +
    • -

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

    +
  • +
    • -
    -

    Summary

    -
      -
    • Version control is a better way to manage shared files than email or shared folders.
      • -
    • The master copy is stored in a repository.
      • -
    • Nobody ever edits the master directory: instead, each person edits a local working copy.
      • -
    • People share changes by committing them to the master or updating their local copy from the master.
      • -
    • The version control system prevents people from overwriting each other's work by forcing them to merge concurrent changes before committing.
      • -
    • It also keeps a complete history of changes made to the master so that old versions can be recovered reliably.
      • -
    • Version control systems work best with text files, but can also handle binary files such as images and Word documents.
      • -
    • Every repository is identified by a URL.
      • -
    • Working copies of different repositories may not overlap.
      • -
    • Each changed to the master copy is identified by a unique revision number.
      • -
    • Revisions identify snapshots of the entire repository, not changes to individual files.
      • -
    • Each change should be commented to make the history more readable.
      • -
    • Commits are transactions: either all changes are successfully committed, or none are.
      • -
    • The basic workflow for version control is update-change-commit.
      • -
    • svn add things tells Subversion to start managing particular files or directories.
      • -
    • svn checkout url checks out a working copy of a repository.
      • -
    • svn commit -m "message" things sends changes to the repository.
      • -
    • svn diff compares the current state of a working copy to the state after the most recent update.
      • -
    • svn diff -r HEAD compares the current state of a working copy to the state of the master copy.
      • -
    • svn history shows the history of a working copy.
      • -
    • svn status shows the status of a working copy.
      • -
    • svn update updates a working copy from the repository.
      • -
    -
    + +
    -
    +