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