version-control/README.md

   1 Version control is a way to keep a track of changing files and store a
   2 history of those changes and the motivation behind them.  This
   3 organized history allows many people in a collaboration to make
   4 changes concurrently, while staying up to date with changes made by
   5 their collaborators.  It also makes it easy to keep yourself organized
   6 if you store similar files in several different locations (e.g. a
   7 project that you develop on both your home computer and your work
   8 computer).
   9
  10 Basic use
  11 =========
  12
  13 Learning objectives
  14 -------------------
  15
  16 * Draw a diagram showing the places version control stores
  17   information.
  18 * Check out a working copy of a repository.
  19 * View the history of changes to a project.
  20 * Add files to a project.
  21 * Commit changes made to the working copy.
  22 * Get changes from an upstream repository.
  23 * Compare the current state of a working copy to the most recent
  24   update from the upstream repository.
  25 * Explain what "version 123 of `xyz.txt`" actually means.
  26
  27 Key points
  28 ----------
  29
  30 * Version control is a better way to manage shared files than email or
  31   shared folders.
  32 * People share their changes by committing them to public repositories
  33   and fetch other's changes by updating their local copy from public
  34   repositories.
  35 * The version control system prevents people from overwriting each
  36   other's work by making merges explicit.
  37 * It also keeps a complete history of changes made to the master so
  38   that old versions can be recovered reliably.
  39 * Version control systems work best with text files, but can also
  40   handle binary files such as images and Word documents.
  41 * Every repository is identified by a URL.
  42 * Each change to the master copy is identified by a unique revision
  43   ID.
  44 * Revisions identify snapshots of the entire repository, not changes
  45   to individual files.
  46 * Each change should be commented to make the history more readable.
  47 * Commits are transactions: either all changes are successfully
  48   committed, or none are.
  49
  50 Merging conflicts
  51 =================
  52
  53 Learning objectives
  54 -------------------
  55
  56 * Explain what causes conflicts to occur and how to tell when one has
  57   occurred.
  58 * Resolve a conflict.
  59
  60 Key points
  61 ----------
  62
  63 * Conflicts must be resolved before a commit can be completed.
  64 * Most version control systems put markers in text files to show
  65   regions of conflict.
  66
  67 Recovering old versions
  68 =======================
  69
  70 Learning objectives
  71 -------------------
  72
  73 * Discard changes made to a working copy.
  74 * Recover an old version of a file.
  75 * Explain what branches are and when they are used.
  76
  77 Key points
  78 ----------
  79
  80 * Recovering an old version of a file may not erase the intervening
  81   changes.
  82 * Use branches to support parallel independent development.
  83
  84 Setting up a repository
  85 =======================
  86
  87 Learning objectives
  88 -------------------
  89
  90 * How to create a repository.
  91
  92 Key points
  93 ----------
  94
  95 * Repositories can be hosted locally, on local (departmental) servers,
  96   on hosting services, or on their owners' own domains.
  97
  98 Provenance
  99 ==========
 100
 101 Learning objectives
 102 -------------------
 103
 104 * What data provenance is.
 105 * How to embed version numbers and other information in files managed
 106   by version control.
 107 * How to record version information about a program in its output.
 108
 109 Key points
 110 ----------
 111
 112 * Put version numbers in programs' output to establish provenance for
 113   data.