From: Greg Wilson Date: Sun, 21 Apr 2013 18:30:16 +0000 (-0400) Subject: Tidying up another section of the instructors' guide on SVN X-Git-Url: http://git.tremily.us/?p=swc-version-control-svn.git;a=commitdiff_plain;h=9877fa8ef5664e8c2f66fe2c1852d9a6168ac6ce Tidying up another section of the instructors' guide on SVN --- diff --git a/svn.html b/svn.html index 494145c..dc61a4e 100644 --- a/svn.html +++ b/svn.html @@ -221,7 +221,7 @@ 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. + whose URL is https://universal.software-carpentry.org/explore. Every repository has an address like this that uniquely identifies the location of the master copy.

@@ -252,24 +252,24 @@ 

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

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

-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
+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.
@@ -284,7 +284,7 @@ Checked out revision 6. 

-$ cd monsters
+$ cd explore
 $ ls
 earth   jupiter mars
 $ ls *
@@ -311,7 +311,7 @@ cydonia.txt  mons-olympus.txt
 
 
 $ pwd
-/home/vlad/monsters
+/home/vlad/explore
 $ ls -a
 .    ..    .svn    earth    jupiter    mars
 $ ls -F .svn
@@ -368,7 +368,7 @@ Send the probe to Mons Olympus?
     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,
+    the explore project is currently at revision 6,
     and all changes so far have been made by the Mummy.
   

 
@@ -855,24 +855,24 @@ $ diff left.txt right.txt
 
 
 
-    

+

+  
Merging Conflicts

 
-      
Merging Conflicts

-
-      

-        
Understand:

-        
    
-          
  • What a conflict in an update is.
    • 
-          
  • How to resolve conflicts when updating.
    • 
-        

-      

+  

+    
Learning Objectives:

+    
    
+      
  • Explain what causes conflicts to occur and how to tell when one has occurred.
    • 
+      
  • Resolve a conflict.
    • 
+      
  • Identify the auxiliary files created when a conflict occurs.
    • 
+    

+  

 
-      

-        Dracula and Wolfman have both synchronized their working copies of monsters
-        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:
-      

+  

+    Dracula and Wolfman have both synchronized their working copies of explore
+    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:
+  

 
 
 Name            Orbital Radius  Orbital Period  Mass            Radius
@@ -883,22 +883,23 @@ Ganymede        1070.4          7.154553        1481.9          2631.2
 Callisto        1882.7          16.689018       1075.9          2410.3
 

 
-      

-        He then commits his work,
-        creating revision 9 of the repository
-        (Figure XXX).
-      

+  

+    He then commits his work,
+    creating revision 9 of the repository
+    (Figure 9).
+  

 
-      

-        After Dracula Commits
-      

+  

+    After Dracula Commits
+    
Figure 9: After Dracula Commits

+  

 
-      

-        But while he is doing this,
-        Wolfman is editing his copy
-        to add information about two other minor moons,
-        Himalia and Elara:
-      

+  

+    But while he is doing this,
+    Wolfman is editing his copy
+    to add information about two other minor moons,
+    Himalia and Elara:
+  

 
 
 Name            Orbital Radius  Orbital Period  Mass            Radius
@@ -911,10 +912,10 @@ Callisto        1882.7          16.689018       1075.9          2410.3
 Elara           11740           259.6528        0.008           40.0
 

 
-      

-        When Wolfman tries to commit his changes to the repository,
-        Subversion won't let him:
-      

+  

+    When Wolfman tries to commit his changes to the repository,
+    Subversion won't let him:
+  

 
 
 $ svn commit -m "Added data for Himalia, Elara"
@@ -924,40 +925,40 @@ svn: File or directory 'moons.txt' is out of date; try updating
 svn: resource out of date; try updating
 

 
-      

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

+  

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

 
-      

-        This does not 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 only 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.
-      

+  

+    This does not 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 only 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.
+  

 
-      

-        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 moons.txt.
-        Wolfman is quicker off the mark this time;
-        he adds a line to the file:
-      

+  

+    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 moons.txt.
+    Wolfman is quicker off the mark this time;
+    he adds a line to the file:
+  

 
 
 Name            Orbital Radius  Orbital Period  Mass            Radius
@@ -971,12 +972,12 @@ Himalia         11460           250.5662        0.095           85.0
 Elara           11740           259.6528        0.008           40.0
 

 
-      

-        and commits it to create revision 11.
-        While he is doing this,
-        though,
-        Dracula inserts a different line at the top of the file:
-      

+  

+    and commits it to create revision 11.
+    While he is doing this,
+    though,
+    Dracula inserts a different line at the top of the file:
+  

 
 
 Name            Orbital Radius  Orbital Period  Mass            Radius
@@ -990,16 +991,16 @@ Himalia         11460           250.5662        0.095           85.0
 Elara           11740           259.6528        0.008           40.0
 

 
-      

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

+  

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

 
 
 $ svn update
@@ -1009,12 +1010,12 @@ Select: (p) postpone, (df) diff-full, (e) edit,
         (s) show all options:
 

 
-      

-        Dracula choose p for "postpone",
-        which tells Subversion that he'll deal with the problem later.
-        Once the update is finished,
-        he opens moons.txt in his editor and sees:
-      

+  

+    Dracula choose p for "postpone",
+    which tells Subversion that he'll deal with the problem later.
+    Once the update is finished,
+    he opens moons.txt in his editor and sees:
+  

 
 
  Name            Orbital Radius  Orbital Period  Mass
@@ -1030,24 +1031,24 @@ Select: (p) postpone, (df) diff-full, (e) edit,
  Callisto        1882.7          16.689018       1075.9
 

 
-      

-        As we can see,
-        Subversion has inserted
-        conflict markers
-        in moons.txt
-        wherever there is a conflict.
-        The line <<<<<<< .mine shows the start of the conflict,
-        and is followed by the lines from the local copy of the file.
-        The separator ======= is then
-        followed by the lines from the repository's file that are in conflict with that section,
-        while >>>>>>> .r11 marks the end of the conflict.
-      

+  

+    As we can see,
+    Subversion has inserted
+    conflict markers
+    in moons.txt
+    wherever there is a conflict.
+    The line <<<<<<< .mine shows the start of the conflict,
+    and is followed by the lines from the local copy of the file.
+    The separator ======= is then
+    followed by the lines from the repository's file that are in conflict with that section,
+    while >>>>>>> .r11 marks the end of the conflict.
+  

 
-      

-        Before he can commit,
-        Dracula has to edit his copy of the file to get rid of those markers.
-        He changes it to:
-      

+  

+    Before he can commit,
+    Dracula has to edit his copy of the file to get rid of those markers.
+    He changes it to:
+  

 
 
 Name            Orbital Radius  Orbital Period  Mass            Radius
@@ -1061,109 +1062,159 @@ Himalia         11460           250.5662        0.095           85.0
 Elara           11740           259.6528        0.008           40.0
 

 
-      

-        then uses the svn resolved command to tell Subversion that
-        he has fixed the problem.
-        Subversion will now let him commit to create revision 12.
-      

+  

+    then uses the svn resolved command to tell Subversion that
+    he has fixed the problem.
+    Subversion will now let him commit to create revision 12.
+  

 
-      

+  

+    
Auxiliary Files

+
+    

+      When Dracula did his update and Subversion detected the conflict in moons.txt,
+      it created three temporary files to help Dracula resolve it.
+      The first is called moons.txt.r9;
+      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.
+    

 
-        
Auxiliary Files

+    

+      The second file is moons.txt.r11.
+      This is the most up-to-date revision from the repository—the
+      file as it is including Wolfman's changes.
+      The third temporary file, moons.txt.mine,
+      is the file as it was in Dracula's working copy before he did the Subversion update.
+    

 
-        

-          When Dracula did his update and Subversion detected the conflict in moons.txt,
-          it created three temporary files to help Dracula resolve it.
-          The first is called moons.txt.r9;
-          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.
-        

+    

+      Subversion creates these auxiliary files primarily
+      to help people merge conflicts in binary files.
+      It wouldn't make sense to insert <<<<<<<
+      and >>>>>>> characters into an image file
+      (it would almost certainly result in a corrupted image).
+      The svn resolved command deletes these three extra files
+      as well as telling Subversion that the conflict has been taken care of.
+    

 
-        

-          The second file is moons.txt.r11.
-          This is the most up-to-date revision from the repository—the
-          file as it is including Wolfman's changes.
-          The third temporary file, moons.txt.mine,
-          is the file as it was in Dracula's working copy before he did the Subversion update.
-        

+  

 
-        

-          Subversion creates these auxiliary files primarily
-          to help people merge conflicts in binary files.
-          It wouldn't make sense to insert <<<<<<<
-          and >>>>>>> characters into an image file
-          (it would almost certainly result in a corrupted image).
-          The svn resolved command deletes these three extra files
-          as well as telling Subversion that the conflict has been taken care of.
-        

+  

+    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 Diffuse and WinMerge.
+    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
+    (Figure 10):
+  

 
-      

+  

+    A Difference Viewer
+    
Figure 10: A Difference Viewer

+  

 
-      

-        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 Diffuse and WinMerge.
-        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
-        (Figure XXX):
-      

+  

+    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 svn resolved and svn commit
+    to create revision 12 of the repository.
+  

 
-      

-        A Difference Viewer
-      

+  

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

 
-      

-        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 svn resolved and svn commit
-        to create revision 12 of the repository.
-      

+  

+    
Working With Multiple Files

 
-      

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

+    

+      As mentioned earlier,
+      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.
+    

 
-      

+  

+
+  

+    
Summary

+    
    
+      
  • Conflicts must be resolved before a commit can be completed.
    • 
+      
  • Subversion puts markers in text files to show regions of conflict.
    • 
+      
  • For each conflicted file, Subversion creates auxiliary files containing the common parent, the master version, and the local version.
    • 
+      
  • svn resolve files tells Subversion that conflicts have been resolved.
    • 
+    

+  

 
-        
Working With Multiple Files

+  

+    
Challenges

 
-        

-          As mentioned earlier,
-          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.
-        

+    

+      If you are working in a group,
+      partner with someone who has also wrote a biography for themselves
+      for the previous section's challenges.
+    

 
-      

+    
    
+      
  1. 
+        Both partners use svn update
+        to make sure their working copies are up to date
+        and that there are no local changes.
+      
    2. 
+      
  2. 
+        The first partner edits her biography and commits the changes.
+      
    3. 
+      
  3. 
+        The second partner edits her copy of the file
+        (without having updated to get the first partner's changes),
+        then tries to svn commit.
+      
    4. 
+      
  4. 
+        Once the second partner has resolved the conflict,
+        she commits her changes.
+      
    5. 
+      
  5. 
+        Repeat these four steps with roles reversed.
+      
    6. 
+    

 
-      

-        
Summary

-        
    
-          
  • Conflicts must be resolved before a commit can be completed.
    • 
-          
  • Subversion puts markers in text files to show regions of conflict.
    • 
-          
  • For each conflicted file, Subversion creates auxiliary files containing the common parent, the master version, and the local version.
    • 
-          
  • svn resolve files tells Subversion that conflicts have been resolved.
    • 
-        

-      

+    

+      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.
+      Figure 11 shows
+      the differences between these two challenges.
+    

 
-    

+    

+      Practicing Conflict Resolution
+      
Figure 11: Practicing Conflict Resolution

+    

+  
+
+

 
     

 
@@ -1182,7 +1233,7 @@ Elara           11740           259.6528        0.008           40.0
         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 monsters is in sync with the head at revision 12.
+        his copy of explore is in sync with the head at revision 12.
         He decides to edit the file moons.txt;
         unfortunately, he forgot that there was a full moon,
         so his changes don't make a lot of sense: