Lesson-2:-Version-Control.rest

   1
   2 ----------------------------------------------------------------------------------
   3 What is Version Control
   4 ----------------------------------------------------------------------------------
   5
   6 Very briefly, version control is a way to keep a backup of changing files, to
   7 store a history of those changes, and most importantly to allow many people in
   8 a collaboration to make changes to the same files concurrently. There are a lot
   9 of verson control systems. Wikipedia provides both a nice vocabulary list and a
  10 fairly complete table of some popular version control systems and their
  11 equivalent commands.
  12
  13 Today, we'll be using SVN. Perhaps someday we'll have a second section of this
  14 experiment to go over distributed version control systems like mercurial.
  15
  16 ----------------------------------------------------------------------------------
  17 Checking Out The Code
  18 ----------------------------------------------------------------------------------
  19
  20 The Hacker Within has its own online code repository. You can check out code
  21 from it at any time, from anywhere. You checked out some code this morning from
  22 it at googlecode http://code.google.com/p/scbc-2011 in smartsvn. If you gave me
  23 a google id, you are a fully fledged reading writing member today. Remember,
  24 with great power comes great responsibility.
  25
  26 Today, we'll check out an svn type repository at scbc-2011.googlecode.com/svn/
  27 .
  28
  29 **********************************************************************************
  30 Exercise : Checking out the code
  31 **********************************************************************************
  32
  33 Step 1 : Open up an internet browser and log in to google.
  34
  35 Step 2 : Now go to the Checkout the source tab and click on the Password link.
  36 Take Note.
  37
  38 Step 3 : Either do this in SmartSVN or crack open a terminal. In SmartSVN,
  39 click on the radio button that says check out project from repository. The
  40 repository location is https://scbc-2011.googlecode.com/svn/ .
  41
  42 In the terminal, if your google user name is buckybadger, do this:
  43
  44 ::
  45
  46   ~$ svn checkout https://scbc-2011.googlecode.com/svn/ \
  47   scbc-2011 --username buckybadger
  48
  49 Step 4 : You should see many files download themselves onto your machine. Let's
  50 make sure it worked. Either browse in SmartSVN or change directories to the
  51 source code and list the contents.
  52
  53 ::
  54
  55   ~$ cd scbc-2011 ~/scbc-2011$ ls
  56
  57
  58 ----------------------------------------------------------------------------------
  59 Checking The Status of Your Local Copy
  60 ----------------------------------------------------------------------------------
  61
  62 The files you've created on your machine are your local "working" copy. The
  63 changes your make in this local copy aren't backed up online automatically.
  64 Until you commit them, the changes you make are local changes. When you change
  65 anything, your set of files becomes different from the files in the official
  66 repository copy. To find out what's different about them in the terminal, try:
  67
  68 ::
  69
  70   ~/scbc-2011$ svn status
  71
  72
  73 The null result means that you're up to date with the
  74 current version of the repository online! There are a few other responses you
  75 might get if you or your collaborators have been active. We'll see what they
  76 are as we go along.
  77
  78 ----------------------------------------------------------------------------------
  79 Updating
  80 ----------------------------------------------------------------------------------
  81
  82 Updating is like voting. You should update early and often , and particularly
  83 before you make or commit any changes. This will ensure you're working with the
  84 most up-to-date version of the repository. Updating won't overwrite any changes
  85 you've made locally without asking, so don't get nervous. When in doubt,
  86 update.
  87
  88 ::
  89
  90   ~/scbc-2011$ svn update
  91   At revision 19.
  92
  93 ----------------------------------------------------------------------------------
  94 Adding New Files to Version Control
  95 ----------------------------------------------------------------------------------
  96
  97 This is great. You can make some changes, and commit them to version control.
  98 But, what if you want to add something totally new? How do you make changes to
  99 a file that doesn't exist yet?
 100
 101 **********************************************************************************
 102 Exercise : Adding files to Version Control
 103 **********************************************************************************
 104
 105 Step 1: Create a wiki page about yourself. Please tell us about yourself. Save
 106 a file to the folder called wiki. Call it something unique, like
 107 buckybadger.wiki. Take your time.
 108
 109 ::
 110
 111   ~/scbc-2011$ vi buckybadger.wiki
 112
 113 Step 2: Check the status of your local copy For kicks, let's see what SVN
 114 thinks of this.
 115
 116 ::
 117
 118   ~/scbc-2011$ svn status
 119
 120 SVN should report that it hasn't yet been officially introduced to your file.
 121
 122 ::
 123
 124   ? buckybadger.wiki
 125
 126 Step 3: Add the file to version control Now, introduce your file to svn by
 127 adding it to version control.
 128
 129 ::
 130
 131   ~/scbc-2011$ svn add wiki/buckybadger.wiki
 132   A wiki/buckybadger.wiki
 133
 134 If you want to, commit that change. Your wiki page will be available for anyone
 135 to see on the repo. When your done, give it a look online at
 136 scbc-2011.googlecode.com/wiki.
 137
 138 ::
 139
 140   ~/scbc-2011$ svn commit -m "In commit messages, we usually explain what we've \
 141   done. Here, we've added a wiki page."
 142   Adding wiki/buckybadger.wiki
 143   Transmitting file data .
 144   Committed revision 86.
 145
 146 ----------------------------------------------------------------------------------
 147 Removing Files from Version Control
 148 ----------------------------------------------------------------------------------
 149
 150 But, let's say you're shy and change your mind about adding this to version
 151 control. Not all pretty faces belong on the internet, after all. If you change
 152 your mind, and would rather not add this wiki page, try svn remove. You can
 153 also just say rm. Be careful, this will delete your local copy of the file.
 154
 155 ::
 156
 157   ~/scbc-2011/wiki$ svn remove buckybadger.wiki
 158   D buckybadger.wiki
 159   ~/scbc-2011/wiki$ svn commit -m "a log message"
 160
 161 Deleting hacker-poke/data/myPic.png Committed revision 87.
 162
 163 Making and Committing a Change
 164
 165 Now, recall the software-carpentry.org tutorial. You're Wolfman. The guy next
 166 to you, he's Dracula. I'll be the Mummy. Please pick a random place in one of
 167 the files and insert a comment, like an easter egg.
 168
 169 **********************************************************************************
 170 Exercise : Making Changes
 171 **********************************************************************************
 172
 173 Step 1 : Insert something
 174
 175 If you're not in the terminal, just open up the ReadMe.wiki file.
 176
 177 If you're new to the command line, you can open the best text editor like so:
 178
 179 ::
 180
 181   ~/scbc-2011$ cd wiki
 182   ~/scbc-2011/wiki$ vi ReadMe.wiki
 183
 184 Once it's open, you'll see some text. Just type the letter 'i' and place a line
 185 anywhere you like. The line is a comment if it begins with a pound sign #, like
 186 so:
 187
 188 ::
 189
 190   #summary A Readme for the Repository
 191   =Read Me=
 192
 193   #KATY'S COMMENT
 194   ==Software Dependencies==
 195   * Python 2.71 (or greater?)
 196   * Nose
 197   * Idle
 198   * sqlite (3?)
 199   * Smart SVN ?
 200   * add more here...
 201
 202
 203 To save it, press 'ESC', then ':wq' .
 204
 205 Step 2 : Check the status of your local copy
 206
 207 Now that you've changed a file, let's see what SVN thinks about your local
 208 status.
 209
 210 ::
 211
 212   ~/scbc-2011$ svn status
 213
 214   M ReadMe.wiki
 215
 216
 217
 218 If you want, try committing your change. If it's a comment, it won't break
 219 anything. If you think someone else has committed recently, don't forget to
 220 update first.
 221
 222 ::
 223
 224   ~/scbc-2011$ svn update
 225
 226
 227
 228 If SVN lets you know that someone else has committed changes to the same file
 229 recently, hang on and watch until the next section on conflicts. If svn doesn't
 230 complain, commit.
 231
 232 Step 3 : Commit
 233
 234 ::
 235
 236   ~/scbc-2011$ svn commit -m "The m flag indicates that you'd like to leave a log \
 237   message saying what you've done. Here, we each added a comment."
 238
 239 The m flag allows you to add a comment that will be stored in the repository to
 240 help your collaborators keep track of the changes.
 241
 242 ----------------------------------------------------------------------------------
 243 Resolving Conflicts
 244 ----------------------------------------------------------------------------------
 245
 246 Some of you may have received an error message about a conflict.
 247
 248 **********************************************************************************
 249 Exercise: Resolving Conflicts
 250 **********************************************************************************
 251
 252 Step 1 : Update Before Committing
 253
 254 ::
 255
 256   $ svn update
 257
 258   U ReadMe.wiki
 259
 260   Conflict discovered in 'ReadMe.wiki'.
 261
 262   Select: (p) postpone, (df) diff-full, (e) edit, (h) help for more options:
 263
 264 Step 2 : Postpone
 265
 266
 267 The options are many :
 268
 269 ::
 270
 271   (p) postpone - mark the conflict to be resolved later (df) diff-full - show
 272   all changes made to merged file (e) edit - change merged file in an editor (r)
 273   resolved - accept merged version of file (mf) mine-full - accept my version of
 274   entire file (ignore their changes) (tf) theirs-full - accept their version of
 275   entire file (lose my changes) (l) launch - launch external tool to resolve
 276   conflict (h) help - show this list For now, you want to do some analysis, so
 277   press p to postpone.
 278
 279   $ p
 280
 281 Step 3 : Check the Differences
 282
 283 Try diff (or meld if you have it).
 284
 285 ::
 286
 287   $ diff myfile1.py myfile2.py Step 4 : Resolve the Conflict
 288
 289 The svn command resolve in combination with --accept and one of the choices
 290 from before will automatically delete the right files. Alternatively, you could
 291 delete all of the files that you don't like, move the correct one to the right
 292 filename, and try committing again. For now, we'll do it the clean way. For
 293 example, pretend you'd like to accept yours rather than the other.
 294
 295 ::
 296
 297   $ svn resolve --accept ReadMe.wiki.mine Resolved conflicted state of
 298   'ReadMe.wiki'
 299
 300 Importantly, if you decide to neglect all of your changes instead, you can
 301 choose to revert. Try svn help revert to find out how to do that.
 302
 303 ::
 304
 305   $ svn revert ReadMe.wiki
 306
 307
 308
 309 ----------------------------------------------------------------------------------
 310 A test
 311 ----------------------------------------------------------------------------------
 312
 313 Okay Wolfmen, open up KatyHuff.wiki and replace my name with your own (or
 314 someone else's, in case you're shy).
 315
 316 Now, clearly we've all just tried to change the same thing at once. The first
 317 one of us to update and commit will have no problems. However, when the rest of
 318 us try, SVN won't let us merge our changes. We have to talk this one over and
 319 decide who gets to commit. The rest of us will have to resolve conflicts as we
 320 learned. Try it!