1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/misc/hg-cheatsheet.txt	Fri Jul 01 10:21:30 2005 +0000
     1.3 @@ -0,0 +1,422 @@
     1.4 +
     1.5 +Mercurial(hg) Cheatsheet for Xen
     1.6 +================================
     1.7 +
     1.8 +Written by Andrew Warfield, extended by Michael Fetterman and Ian Pratt
     1.9 +June 29, 2005
    1.10 +
    1.11 +Overview
    1.12 +--------
    1.13 +The Xen project has moved from BitKeeper to Mercurial for source
    1.14 +control.  This note aims to provide a quick guide to getting up and
    1.15 +running with the new tools as quickly as possible, and is written from
    1.16 +the perspective of someone who has been using BK.
    1.17 +
    1.18 +For a more detailed exposition, see the mecurial tutorial:
    1.19 + http://www.serpentine.com/mercurial/index.cgi?Tutorial
    1.20 +
    1.21 +The Hg manpage is available at:
    1.22 + http://www.selenic.com/mercurial/hg.1.html
    1.23 +
    1.24 +There's also a very useful FAQ that explains the terminology:
    1.25 + http://www.selenic.com/mercurial/FAQ.html
    1.26 +
    1.27 +There's also a good README:
    1.28 + http://www.selenic.com/mercurial/README
    1.29 +
    1.30 +Necessary software
    1.31 +------------------
    1.32 +Mercurial is available at:
    1.33 +  http://www.selenic.com/mercurial/ 
    1.34 +
    1.35 +You will also need a Python version >= 2.3
    1.36 +
    1.37 +How Mercurial is different from BK
    1.38 +----------------------------------
    1.39 +There are several pertinent differences between hg and bk.  This
    1.40 +section aims to give an overview of the conceptual differences between
    1.41 +the two SCMs -- if you just want examples to get going, skip ahead to
    1.42 +"Getting Xen". The key differences are:
    1.43 +
    1.44 +  - No explicit per-file locking.  You do not need to explicitly 
    1.45 +    check a file out before editing it.
    1.46 +  - No notion (currently) of file renames.
    1.47 +  - A repository can have multiple active heads.
    1.48 +  - Automatic merge support is currently inferior to BK's.
    1.49 +  - No graphical tools.
    1.50 +  - No per-file revision history, only per-changeset (we never really used this anyhow)
    1.51 +  - Hg repositories tend to be rather bigger than Bk ones, but Hg does seem faster.
    1.52 +
    1.53 +Mercurial is based on the notion of changesets as complete, immutable,
    1.54 +versions of the repository.  You make changes to a working version of
    1.55 +the repository that is based on a particular changeset.  When you
    1.56 +commit, you will generate a new child changeset with whatever changes
    1.57 +you choose to apply.
    1.58 +
    1.59 +A major difference between Hg and BK is that you aren't forced to
    1.60 +resolve conflicts immediately: BK forced you to resolve conflicts
    1.61 +immediately on any merge, and it then immediately created a changeset
    1.62 +with those conflicts' resolutions.  Frequently, you then had to add
    1.63 +yet another changeset to fixup the things for which the automatic
    1.64 +merge yielded bad results. Hg puts the results of the merge into your
    1.65 +work directory, and remembers what you merged with (so that it can
    1.66 +later record both of the merge parents, if you decide to make a
    1.67 +changeset), but it doesn't immediately create a changeset.
    1.68 +
    1.69 +A further feature of Hg is that it allows a repository to have
    1.70 +multiple heads. This means that you can have changesets with no common
    1.71 +descendent in one repository -- something BK won't allow. This is
    1.72 +actually pretty neat. For example, it would in principle enable you to
    1.73 +have both the 2.0-testing and unstable trees in a single
    1.74 +repository. We shyed away from doing this as we thought the risk of
    1.75 +commiting to the wrong head was too great.
    1.76 +
    1.77 +One slightly confusing aspect of Hg is that many of the commands have
    1.78 +aliases, and hence when looking things up in the man page its not
    1.79 +always obvious what the underlying command is. For example 'co' is
    1.80 +actually an alias for the 'update' command, but 'co' seems to make
    1.81 +more sense, at least to RCS refugees like me.
    1.82 +
    1.83 +
    1.84 +Getting Xen
    1.85 +-----------
    1.86 +
    1.87 +The URL for the mainline Xen mercurial respository is:
    1.88 +
    1.89 +   http://xenbits.xensource.com/xen-unstable.hg
    1.90 +   (similarly for xen-2.0 and xen-2.0-testing)
    1.91 +
    1.92 +You can point a browser and this and use Hg's web interface to view
    1.93 +revision history, or use it as the nominated source when issuing
    1.94 +"hg init" or "hg pull" commands. 
    1.95 +
    1.96 +However, to avoid taxing the Mercurial server with a complete pull of
    1.97 +the Xen repository, it is best to download a tarball of a seed
    1.98 +repository from:
    1.99 + 
   1.100 +  http://www.cl.cam.ac.uk/Research/SRG/netos/xen/downloads/xen-unstable.hg.tar.gz
   1.101 +
   1.102 +Untar the repository on your disk, cd into it, and then pull the most
   1.103 +recent changes:
   1.104 +
   1.105 +  hg pull -u
   1.106 +
   1.107 +By default hg does not automatically checkout ('update') files from
   1.108 +the repository as used to happen with bk. The above is equivalent to
   1.109 +"hg pull; hg co"
   1.110 +
   1.111 +The repository parent is stored in a repository configuration file, 
   1.112 +.hg/hgrc, from the repository root.  If you look at this file, you 
   1.113 +will see:
   1.114 +
   1.115 +  |  [paths]
   1.116 +  |  default = http://xenbits.xensource.com/xen-unstable.hg
   1.117 +
   1.118 +"default" specifies the appropriate parent repository for hg to pull 
   1.119 +from.  Hg allows you to pull additional repositories, for instance if 
   1.120 +you want to work between unstable and testing concurrently.
   1.121 +
   1.122 +The command "hg pull" simply adds changesets to your repository,
   1.123 +without any merging of any kind.  "hg pull -u" implies merging with
   1.124 +the current state of your working directory.  If you weren't already
   1.125 +"updated" to your local repository's tip, you might be surprised to
   1.126 +find yourself merging the results of the pull with a non-tip node in
   1.127 +your local repository.  
   1.128 +
   1.129 +
   1.130 +Revision History
   1.131 +----------------
   1.132 +
   1.133 +You can view the repository revision history with:
   1.134 +
   1.135 +   hg history
   1.136 +
   1.137 +In practice, you'll probably want to use pipe the output through
   1.138 +'head' or 'more' as it prints the entire history.
   1.139 +
   1.140 +Looking at the first few lines of output, you can see the changeset at
   1.141 +the head of the current branch, known as the 'tip' (the tip is
   1.142 +automatically given a special tag to make it easy to refer to):
   1.143 +
   1.144 +   | changeset:   5599:6cbf9ec05cd9e05c0c46a85df7fc00262633cd3d
   1.145 +   | tag:         tip
   1.146 +   | user:        kaf24@firebug.cl.cam.ac.uk
   1.147 +   | date:        Tue Jun 28 18:47:14 2005
   1.148 +   | summary:     bitkeeper revision 1.1768 (42c18d2259NPELcGV7ohyZNh72ufSw)
   1.149 +
   1.150 +By default, Hg just shows the first line of the changset comments. You
   1.151 +can find further information with "hg -v history".
   1.152 +
   1.153 +The changeset identifier has two parts, a _local_ monotonically
   1.154 +increasing changeset id, 4792 above, and a _global_ hash, which
   1.155 +follows the colon on the changeset line.  The hash uniquely identifies
   1.156 +the changeset and its lineage back to the root of the changeset tree
   1.157 +-- it is useful for distributed management and so on.  However, as it
   1.158 +is a bit unruly, the local id will allow you to work easily with the
   1.159 +local repo. Hg commands will take either identifier. Additionally, a
   1.160 +tags mechanism lets you give common names to specific changesets.
   1.161 +
   1.162 +You should always use the global hash when referring to versions of
   1.163 +the mainline Xen respoitory. With Bk you could often get away with
   1.164 +using the shortform version, but with Hg the local ids are pretty much
   1.165 +guaranteed to be different.
   1.166 +
   1.167 +
   1.168 +Creating a child repository from an existing repository
   1.169 +-------------------------------------------------------
   1.170 +If you wanted to create additional local child repositories,
   1.171 +
   1.172 +   hg init [path or url]
   1.173 +
   1.174 +is effectively equivalent to bk clone.  The major difference is that 
   1.175 +it should be run from the root of your new repository.  So:
   1.176 +
   1.177 +   bk clone /foo/bar
   1.178 +
   1.179 +would be replaced with:
   1.180 +
   1.181 +   mkdir bar
   1.182 +   cd bar
   1.183 +   hg init /foo/bar
   1.184 +
   1.185 +NB: newer version of Hg support a 'clone' command that works in the
   1.186 +same manner as bk.
   1.187 +
   1.188 +Editing files
   1.189 +-------------
   1.190 +
   1.191 +Normal edits may be made in place.  File creation needs explicit
   1.192 +marking, though deletes should be picked up automatically
   1.193 +
   1.194 +creation:
   1.195 +
   1.196 +   touch a (or otherwise created a file)
   1.197 +   hg add a
   1.198 +
   1.199 +You can see what has changed using:
   1.200 +
   1.201 +   hg status
   1.202 +
   1.203 +   | C foo/foo.c
   1.204 +   | R foo/bar.c
   1.205 +   | ? a.txt
   1.206 +
   1.207 +This shows that in the current repo, foo.c has been changed, bar.c has
   1.208 +been deleted, and a.txt is new, but has not been added.  '?' changes
   1.209 +to 'A' after "hg add a.txt". There is a .hgignore file which contains
   1.210 +regexps of files that should be ignored when scanning for new
   1.211 +files. We try to ensure that all the generated files in a build are
   1.212 +covered by the regexps.
   1.213 +
   1.214 +You can add all the new files in a repository with "hg addremove". If
   1.215 +you discover that you've added a file you didn't want, you can remove
   1.216 +it from the list of files to be included in the next commit using
   1.217 +"hg forget".
   1.218 +
   1.219 +Committing changes
   1.220 +-----------------
   1.221 +
   1.222 +After you've checked that hg knows about any new files you've created,
   1.223 +you probably want to see a diff of what you're about to commit. You
   1.224 +can do this with:
   1.225 +   
   1.226 +   hg diff
   1.227 +
   1.228 +Once you're happy with what you have, invoke:
   1.229 +
   1.230 +   hg commit
   1.231 +
   1.232 +This will pop up an editor with a list of files to be committed to the
   1.233 +repository.  It will look vaguely like this:
   1.234 +
   1.235 +   | 
   1.236 +   | HG: manifest hash 6397b04bd5c2a992482d973b685a7e5e498788e7
   1.237 +   | HG: changed doc/thesis/new.tex
   1.238 +   | HG: removed doc/2005-hotdep-protection/paper.tex
   1.239 +
   1.240 +Your comments can go anywhere in this file.  The first line is the 
   1.241 +most important, as it will show as the changeset description in 
   1.242 +non-verbose-mode history listings.
   1.243 +
   1.244 +You can do commits without the editor and of partial sets of files 
   1.245 +using command-line switches. See:
   1.246 +
   1.247 +   hg help commit
   1.248 +
   1.249 +You can use the -A (--addremove) flag to commit e.g. "hg -A commit" to
   1.250 +ask mercurial to scan the tree looking for newly created files to add
   1.251 +in to the changeset. This avoids having to explicitly use "hg add",
   1.252 +but you probably want to be careful of adding any new generated files
   1.253 +too.
   1.254 +
   1.255 +
   1.256 +Generating a patch
   1.257 +------------------
   1.258 +Generating a patch is easy,
   1.259 +
   1.260 +   hg export [changeset]
   1.261 +
   1.262 +will generate a patch describing the diff between that changeset and 
   1.263 +its parent.
   1.264 +
   1.265 +Pushing changesets to a parent repository
   1.266 +-----------------------------------------
   1.267 +
   1.268 +   hg push
   1.269 +
   1.270 +Pushes changes up to a parent. You can't push if you pulled the
   1.271 +repository off the web interface. In fact, you can currently only push
   1.272 +to an ssh target -- filesystem drectory targets don't work, but this
   1.273 +will be fixed soon.
   1.274 +
   1.275 +
   1.276 +Repository history
   1.277 +------------------
   1.278 +
   1.279 +Here are a collection of common commands to get you started:
   1.280 +
   1.281 +   hg history | less
   1.282 +
   1.283 +shows the history of changesets, starting from the most recent.  You 
   1.284 +want to pipe it to some sort of pager.  For more complete details,
   1.285 + 
   1.286 +   hg -v history | less
   1.287 +
   1.288 +will include files modified and full (not just first-line) comments.
   1.289 +
   1.290 +Additionally, you can see just the tip (head of the current
   1.291 +branch) of the repository by typing:
   1.292 +
   1.293 +   hg [-v] tip
   1.294 +
   1.295 +
   1.296 +Moving to a specific changeset
   1.297 +------------------------------
   1.298 +
   1.299 +The co command lets you change the working version of the repository
   1.300 +to a different changeset. 
   1.301 +
   1.302 +   hg co [changeset]
   1.303 +
   1.304 +NB: 'co' is an alias for 'update'
   1.305 +
   1.306 +This command enables you to rewind the working repository to previous
   1.307 +changesets, for example to isolate the changeset in which a bug is
   1.308 +introduced.
   1.309 +
   1.310 +If you try and do a 'co' but have modified files in your repository Hg
   1.311 +won't let you unless you ask it explicitly to merge the checked out
   1.312 +version into the current tree using the "-m" option. The "-C"
   1.313 +(--clean) option will force overwrite any locally modified files.
   1.314 +
   1.315 +Any commits that are made to non-head changesets will obviously fork
   1.316 +the tree, creating a new head. You can see all the heads in a tree with
   1.317 +"hg heads".
   1.318 +
   1.319 +In general, "hg co" does the right thing, although it doesn't
   1.320 +currently seem to clean up unused directories that have been created
   1.321 +by other checked-out versions. This can confuse the Xen build
   1.322 +system. Hg will probably get fixed soon, but in the meantime you can
   1.323 +cleanup with "find -depth -type d -print | xargs -r rmdir".
   1.324 +
   1.325 +You can return to the tip by ommiting an explicit changeset id.
   1.326 +   
   1.327 +The manifest command lets you see the contents of the repository for 
   1.328 +the current changeset.
   1.329 +
   1.330 +   hg manifest
   1.331 +
   1.332 +This will print a bunch of records of the form: 
   1.333 +
   1.334 +   | 98856c45c35a504bc6da06a62b7787ddfdfd1c8b 644 COPYING
   1.335 +   | f28971eedc5b54e7a9b26dd18d52992955354981 644 Config.mk
   1.336 +   | a3575cc4db59e50bbac8a039a0c74f081a8dfc4f 644 Makefile
   1.337 +   | 7fc869aae2945a9f4626fad96552db3103e61cb9 644 README
   1.338 +   | ...
   1.339 +
   1.340 +This lists the hash of each file, its 1-bit 'executable' atribute
   1.341 +(either file permission mode 644 or 755), and the file name.  So, to
   1.342 +determine the files that change across two changesets, you would dump
   1.343 +the respective manifests to files, and use diff.
   1.344 +
   1.345 +
   1.346 +Managing changeset tags
   1.347 +-----------------------
   1.348 +To create a tag to the current changeset:
   1.349 +
   1.350 +   hg tag tagname
   1.351 +
   1.352 +This will _immediately_ generate a changeset with a change to the file
   1.353 +.hgtags in the repository root.   The new tag in this file will look
   1.354 +something like:
   1.355 +
   1.356 +   | 35159ed4b30538e7a52c60ad0a63f7e9af156e4c tagname
   1.357 +
   1.358 +and may be used to identify that changeset throughout the repo.
   1.359 +Storing tags in this file and generating changesets immediately 
   1.360 +forces people to merge and keep tags up to date across the repository.
   1.361 +
   1.362 +Note that tags are resolved by searching .hgtags in each of the 
   1.363 +repository heads, sequentially, and using the first match.  "hg heads"
   1.364 +lists the current heads.
   1.365 +
   1.366 +The "hg tags" command, will lists all the currently valid tags.
   1.367 +
   1.368 +
   1.369 +Hg server and source browser
   1.370 +----------------------------
   1.371 +
   1.372 +   hg serve -p port
   1.373 +
   1.374 +Launches a web server on the specified port, serving a source browser 
   1.375 +for the repository.  This browser may be used to examine the 
   1.376 +changeset history, view annotated source files, generate diffs.  
   1.377 +Additionally "hg pull" may be run against it.
   1.378 +
   1.379 +Additional useful commands
   1.380 +(that probably only need one-line descriptions)
   1.381 +-----------------------------------------------
   1.382 +
   1.383 +(Slightly) more detail on all of these is available with
   1.384 +
   1.385 +  hg help [command]
   1.386 +
   1.387 +Shows the differences between whatever changeset you most recently
   1.388 +checked out, and your current working directory:
   1.389 +
   1.390 +   hg diff
   1.391 +
   1.392 +View an annotated version of a source file:
   1.393 +
   1.394 +   hg annotate
   1.395 +
   1.396 +Get a historical version of a file:
   1.397 +
   1.398 +   hg cat
   1.399 +
   1.400 + NB: Most commands accepting a version number want the changeset's
   1.401 + version number.  "hg cat" is different in that it wants the
   1.402 + *file*'s version number.
   1.403 +
   1.404 +Unadd a file to the current commit:
   1.405 +
   1.406 +   hg forget
   1.407 +
   1.408 +List all heads in the current repository:
   1.409 +
   1.410 +   hg heads
   1.411 +
   1.412 +Undo exactly one (and ONLY one) changeset:
   1.413 +
   1.414 +   hg undo
   1.415 +
   1.416 +Show the parents of a changeset:
   1.417 +
   1.418 +   hg parents
   1.419 +
   1.420 + NB: Changesets have either one or two parent changesets. If your
   1.421 + working directory contains the uncommitted results of a merge, then
   1.422 + you have two parents.  Otherwise, the single parent is the changeset
   1.423 + which you most recently checked out.
   1.424 +
   1.425 +