version-control/README.md

   1 Basic use
   2 =========
   3
   4 Learning objectives
   5 -------------------
   6
   7 * Draw a diagram showing the places version control stores
   8   information.
   9 * Check out a working copy of a repository.
  10 * View the history of changes to a project.
  11 * Explain why working copies of different projects should not overlap.
  12 * Add files to a project.
  13 * Commit changes made to a working copy to a repository.
  14 * Update a working copy to get changes from the repository.
  15 * Compare the current state of a working copy to the last update from
  16   the repository, and to the current state of the repository.
  17 * Explain what "version 123 of `xyz.txt`" actually means.
  18
  19 Key points
  20 ----------
  21
  22 * Version control is a better way to manage shared files than email or
  23   shared folders.
  24 * The master copy is stored in a repository.
  25 * Nobody ever edits the master directory: instead, each person edits a
  26   local working copy.
  27 * People share changes by committing them to the master or updating
  28   their local copy from the master.
  29 * The version control system prevents people from overwriting each
  30   other's work by forcing them to merge concurrent changes before
  31   committing.
  32 * It also keeps a complete history of changes made to the master so
  33   that old versions can be recovered reliably.
  34 * Version control systems work best with text files, but can also
  35   handle binary files such as images and Word documents.
  36 * Every repository is identified by a URL.
  37 * Working copies of different repositories may not overlap.
  38 * Each changed to the master copy is identified by a unique revision
  39   number.
  40 * Revisions identify snapshots of the entire repository, not changes
  41   to individual files.
  42 * Each change should be commented to make the history more readable.
  43 * Commits are transactions: either all changes are successfully
  44   committed, or none are.
  45 * The basic workflow for version control is update-change-commit.
  46 * `svn add <em>things</em>` tells Subversion to start managing
  47   particular files or directories.
  48 * `svn checkout $URL` checks out a working copy of a repository.
  49 * `svn commit -m "$MESSAGE" $THINGS` sends changes to the repository.
  50 * `svn diff` compares the current state of a working copy to the state
  51   after the most recent update.
  52 * `svn diff -r HEAD` compares the current state of a working copy to
  53   the state of the master copy.
  54 * `svn history` shows the history of a working copy.
  55 * `svn status` shows the status of a working copy.
  56 * `svn update` updates a working copy from the repository.
  57
  58 Merging conflicts
  59 =================
  60
  61 Learning objectives
  62 -------------------
  63
  64 * Explain what causes conflicts to occur and how to tell when one has
  65   occurred.
  66 * Resolve a conflict.
  67 * Identify the auxiliary files created when a conflict occurs.
  68
  69 Key points
  70 ----------
  71
  72 * Conflicts must be resolved before a commit can be completed.
  73 * Subversion puts markers in text files to show regions of conflict.
  74 * For each conflicted file, Subversion creates auxiliary files
  75   containing the common parent, the master version, and the local
  76   version.
  77 * `svn resolve $FILES` tells Subversion that conflicts have been
  78   resolved.
  79
  80 Recovering old versions
  81 =======================
  82
  83 Learning objectives
  84 -------------------
  85
  86 * Discard changes made to a working copy.
  87 * Recover an old version of a file.
  88 * Explain what branches are and when they are used.
  89
  90 Key points
  91 ----------
  92
  93 * Old versions of files can be recovered by merging their old state
  94   with their current state.
  95 * Recovering an old version of a file does not erase the intervening
  96   changes.
  97 * Use branches to support parallel independent development.
  98 * `svn revert` undoes local changes to files.
  99 * `svn merge` merges two revisions of a file.
 100
 101 Setting up a repository
 102 =======================
 103
 104 Learning objectives
 105 -------------------
 106
 107 * How to create a repository.
 108
 109 Key points
 110 ----------
 111
 112 * `svnadmin create $NAME` creates a new repository.
 113 * Repositories can be hosted locally, on local (departmental) servers,
 114   on hosting services, or on their owners' own domains.
 115
 116 Provenance
 117 ==========
 118
 119 Learning objectives
 120 -------------------
 121
 122 * What data provenance is.
 123 * How to embed version numbers and other information in files managed
 124   by version control.
 125 * How to record version information about a program in its output.
 126
 127 Key points
 128 ----------
 129
 130 * `$Keyword: …$` in a file can be filled in with a property value each
 131   time the file is committed.
 132 * Put version numbers in programs' output to establish provenance for
 133   data.
 134 * `svn propset svn:keywords $PROPERTY $FILES` tells Subversion to
 135   start filling in property values.