-------- Original Message --------
Subject: Add the Mercurial for Xen cheatsheet into the repo.
Date: Fri, 01 Jul 2005 06:40:10 -0400
From: Xen patchbot -unstable <patchbot-unstable@xxxxxxxxxxxxxxxxxxx>
Reply-To: xen-devel@xxxxxxxxxxxxxxxxxxx
To: James.Bulpin@xxxxxxxxxxxx
# HG changeset patch
# User iap10@xxxxxxxxxxxxxxxxxxxxx
# Node ID a1b5af05f72e72753d93abed115f620bb8a97008
# Parent 132e23381692a706513c698aee0cb9b81a6c5715
Add the Mercurial for Xen cheatsheet into the repo.
Signed-off-by: ian@xxxxxxxxxxxxx
diff -r 132e23381692 -r a1b5af05f72e docs/misc/hg-cheatsheet.txt
--- /dev/null Fri Jul 1 03:16:53 2005
+++ b/docs/misc/hg-cheatsheet.txt Fri Jul 1 10:21:30 2005
@@ -0,0 +1,422 @@
+
+Mercurial(hg) Cheatsheet for Xen
+================================
+
+Written by Andrew Warfield, extended by Michael Fetterman and Ian Pratt
+June 29, 2005
+
+Overview
+--------
+The Xen project has moved from BitKeeper to Mercurial for source
+control. This note aims to provide a quick guide to getting up and
+running with the new tools as quickly as possible, and is written from
+the perspective of someone who has been using BK.
+
+For a more detailed exposition, see the mecurial tutorial:
+ http://www.serpentine.com/mercurial/index.cgi?Tutorial
+
+The Hg manpage is available at:
+ http://www.selenic.com/mercurial/hg.1.html
+
+There's also a very useful FAQ that explains the terminology:
+ http://www.selenic.com/mercurial/FAQ.html
+
+There's also a good README:
+ http://www.selenic.com/mercurial/README
+
+Necessary software
+------------------
+Mercurial is available at:
+ http://www.selenic.com/mercurial/
+
+You will also need a Python version >= 2.3
+
+How Mercurial is different from BK
+----------------------------------
+There are several pertinent differences between hg and bk. This
+section aims to give an overview of the conceptual differences between
+the two SCMs -- if you just want examples to get going, skip ahead to
+"Getting Xen". The key differences are:
+
+ - No explicit per-file locking. You do not need to explicitly
+ check a file out before editing it.
+ - No notion (currently) of file renames.
+ - A repository can have multiple active heads.
+ - Automatic merge support is currently inferior to BK's.
+ - No graphical tools.
+ - No per-file revision history, only per-changeset (we never really
used this anyhow)
+ - Hg repositories tend to be rather bigger than Bk ones, but Hg does
seem faster.
+
+Mercurial is based on the notion of changesets as complete, immutable,
+versions of the repository. You make changes to a working version of
+the repository that is based on a particular changeset. When you
+commit, you will generate a new child changeset with whatever changes
+you choose to apply.
+
+A major difference between Hg and BK is that you aren't forced to
+resolve conflicts immediately: BK forced you to resolve conflicts
+immediately on any merge, and it then immediately created a changeset
+with those conflicts' resolutions. Frequently, you then had to add
+yet another changeset to fixup the things for which the automatic
+merge yielded bad results. Hg puts the results of the merge into your
+work directory, and remembers what you merged with (so that it can
+later record both of the merge parents, if you decide to make a
+changeset), but it doesn't immediately create a changeset.
+
+A further feature of Hg is that it allows a repository to have
+multiple heads. This means that you can have changesets with no common
+descendent in one repository -- something BK won't allow. This is
+actually pretty neat. For example, it would in principle enable you to
+have both the 2.0-testing and unstable trees in a single
+repository. We shyed away from doing this as we thought the risk of
+commiting to the wrong head was too great.
+
+One slightly confusing aspect of Hg is that many of the commands have
+aliases, and hence when looking things up in the man page its not
+always obvious what the underlying command is. For example 'co' is
+actually an alias for the 'update' command, but 'co' seems to make
+more sense, at least to RCS refugees like me.
+
+
+Getting Xen
+-----------
+
+The URL for the mainline Xen mercurial respository is:
+
+ http://xenbits.xensource.com/xen-unstable.hg
+ (similarly for xen-2.0 and xen-2.0-testing)
+
+You can point a browser and this and use Hg's web interface to view
+revision history, or use it as the nominated source when issuing
+"hg init" or "hg pull" commands.
+
+However, to avoid taxing the Mercurial server with a complete pull of
+the Xen repository, it is best to download a tarball of a seed
+repository from:
+
+
http://www.cl.cam.ac.uk/Research/SRG/netos/xen/downloads/xen-unstable.hg.tar.gz
+
+Untar the repository on your disk, cd into it, and then pull the most
+recent changes:
+
+ hg pull -u
+
+By default hg does not automatically checkout ('update') files from
+the repository as used to happen with bk. The above is equivalent to
+"hg pull; hg co"
+
+The repository parent is stored in a repository configuration file,
+.hg/hgrc, from the repository root. If you look at this file, you
+will see:
+
+ | [paths]
+ | default = http://xenbits.xensource.com/xen-unstable.hg
+
+"default" specifies the appropriate parent repository for hg to pull
+from. Hg allows you to pull additional repositories, for instance if
+you want to work between unstable and testing concurrently.
+
+The command "hg pull" simply adds changesets to your repository,
+without any merging of any kind. "hg pull -u" implies merging with
+the current state of your working directory. If you weren't already
+"updated" to your local repository's tip, you might be surprised to
+find yourself merging the results of the pull with a non-tip node in
+your local repository.
+
+
+Revision History
+----------------
+
+You can view the repository revision history with:
+
+ hg history
+
+In practice, you'll probably want to use pipe the output through
+'head' or 'more' as it prints the entire history.
+
+Looking at the first few lines of output, you can see the changeset at
+the head of the current branch, known as the 'tip' (the tip is
+automatically given a special tag to make it easy to refer to):
+
+ | changeset: 5599:6cbf9ec05cd9e05c0c46a85df7fc00262633cd3d
+ | tag: tip
+ | user: kaf24@xxxxxxxxxxxxxxxxxxxx
+ | date: Tue Jun 28 18:47:14 2005
+ | summary: bitkeeper revision 1.1768
(42c18d2259NPELcGV7ohyZNh72ufSw)
+
+By default, Hg just shows the first line of the changset comments. You
+can find further information with "hg -v history".
+
+The changeset identifier has two parts, a _local_ monotonically
+increasing changeset id, 4792 above, and a _global_ hash, which
+follows the colon on the changeset line. The hash uniquely identifies
+the changeset and its lineage back to the root of the changeset tree
+-- it is useful for distributed management and so on. However, as it
+is a bit unruly, the local id will allow you to work easily with the
+local repo. Hg commands will take either identifier. Additionally, a
+tags mechanism lets you give common names to specific changesets.
+
+You should always use the global hash when referring to versions of
+the mainline Xen respoitory. With Bk you could often get away with
+using the shortform version, but with Hg the local ids are pretty much
+guaranteed to be different.
+
+
+Creating a child repository from an existing repository
+-------------------------------------------------------
+If you wanted to create additional local child repositories,
+
+ hg init [path or url]
+
+is effectively equivalent to bk clone. The major difference is that
+it should be run from the root of your new repository. So:
+
+ bk clone /foo/bar
+
+would be replaced with:
+
+ mkdir bar
+ cd bar
+ hg init /foo/bar
+
+NB: newer version of Hg support a 'clone' command that works in the
+same manner as bk.
+
+Editing files
+-------------
+
+Normal edits may be made in place. File creation needs explicit
+marking, though deletes should be picked up automatically
+
+creation:
+
+ touch a (or otherwise created a file)
+ hg add a
+
+You can see what has changed using:
+
+ hg status
+
+ | C foo/foo.c
+ | R foo/bar.c
+ | ? a.txt
+
+This shows that in the current repo, foo.c has been changed, bar.c has
+been deleted, and a.txt is new, but has not been added. '?' changes
+to 'A' after "hg add a.txt". There is a .hgignore file which contains
+regexps of files that should be ignored when scanning for new
+files. We try to ensure that all the generated files in a build are
+covered by the regexps.
+
+You can add all the new files in a repository with "hg addremove". If
+you discover that you've added a file you didn't want, you can remove
+it from the list of files to be included in the next commit using
+"hg forget".
+
+Committing changes
+-----------------
+
+After you've checked that hg knows about any new files you've created,
+you probably want to see a diff of what you're about to commit. You
+can do this with:
+
+ hg diff
+
+Once you're happy with what you have, invoke:
+
+ hg commit
+
+This will pop up an editor with a list of files to be committed to the
+repository. It will look vaguely like this:
+
+ |
+ | HG: manifest hash 6397b04bd5c2a992482d973b685a7e5e498788e7
+ | HG: changed doc/thesis/new.tex
+ | HG: removed doc/2005-hotdep-protection/paper.tex
+
+Your comments can go anywhere in this file. The first line is the
+most important, as it will show as the changeset description in
+non-verbose-mode history listings.
+
+You can do commits without the editor and of partial sets of files
+using command-line switches. See:
+
+ hg help commit
+
+You can use the -A (--addremove) flag to commit e.g. "hg -A commit" to
+ask mercurial to scan the tree looking for newly created files to add
+in to the changeset. This avoids having to explicitly use "hg add",
+but you probably want to be careful of adding any new generated files
+too.
+
+
+Generating a patch
+------------------
+Generating a patch is easy,
+
+ hg export [changeset]
+
+will generate a patch describing the diff between that changeset and
+its parent.
+
+Pushing changesets to a parent repository
+-----------------------------------------
+
+ hg push
+
+Pushes changes up to a parent. You can't push if you pulled the
+repository off the web interface. In fact, you can currently only push
+to an ssh target -- filesystem drectory targets don't work, but this
+will be fixed soon.
+
+
+Repository history
+------------------
+
+Here are a collection of common commands to get you started:
+
+ hg history | less
+
+shows the history of changesets, starting from the most recent. You
+want to pipe it to some sort of pager. For more complete details,
+
+ hg -v history | less
+
+will include files modified and full (not just first-line) comments.
+
+Additionally, you can see just the tip (head of the current
+branch) of the repository by typing:
+
+ hg [-v] tip
+
+
+Moving to a specific changeset
+------------------------------
+
+The co command lets you change the working version of the repository
+to a different changeset.
+
+ hg co [changeset]
+
+NB: 'co' is an alias for 'update'
+
+This command enables you to rewind the working repository to previous
+changesets, for example to isolate the changeset in which a bug is
+introduced.
+
+If you try and do a 'co' but have modified files in your repository Hg
+won't let you unless you ask it explicitly to merge the checked out
+version into the current tree using the "-m" option. The "-C"
+(--clean) option will force overwrite any locally modified files.
+
+Any commits that are made to non-head changesets will obviously fork
+the tree, creating a new head. You can see all the heads in a tree with
+"hg heads".
+
+In general, "hg co" does the right thing, although it doesn't
+currently seem to clean up unused directories that have been created
+by other checked-out versions. This can confuse the Xen build
+system. Hg will probably get fixed soon, but in the meantime you can
+cleanup with "find -depth -type d -print | xargs -r rmdir".
+
+You can return to the tip by ommiting an explicit changeset id.
+
+The manifest command lets you see the contents of the repository for
+the current changeset.
+
+ hg manifest
+
+This will print a bunch of records of the form:
+
+ | 98856c45c35a504bc6da06a62b7787ddfdfd1c8b 644 COPYING
+ | f28971eedc5b54e7a9b26dd18d52992955354981 644 Config.mk
+ | a3575cc4db59e50bbac8a039a0c74f081a8dfc4f 644 Makefile
+ | 7fc869aae2945a9f4626fad96552db3103e61cb9 644 README
+ | ...
+
+This lists the hash of each file, its 1-bit 'executable' atribute
+(either file permission mode 644 or 755), and the file name. So, to
+determine the files that change across two changesets, you would dump
+the respective manifests to files, and use diff.
+
+
+Managing changeset tags
+-----------------------
+To create a tag to the current changeset:
+
+ hg tag tagname
+
+This will _immediately_ generate a changeset with a change to the file
+.hgtags in the repository root. The new tag in this file will look
+something like:
+
+ | 35159ed4b30538e7a52c60ad0a63f7e9af156e4c tagname
+
+and may be used to identify that changeset throughout the repo.
+Storing tags in this file and generating changesets immediately
+forces people to merge and keep tags up to date across the repository.
+
+Note that tags are resolved by searching .hgtags in each of the
+repository heads, sequentially, and using the first match. "hg heads"
+lists the current heads.
+
+The "hg tags" command, will lists all the currently valid tags.
+
+
+Hg server and source browser
+----------------------------
+
+ hg serve -p port
+
+Launches a web server on the specified port, serving a source browser
+for the repository. This browser may be used to examine the
+changeset history, view annotated source files, generate diffs.
+Additionally "hg pull" may be run against it.
+
+Additional useful commands
+(that probably only need one-line descriptions)
+-----------------------------------------------
+
+(Slightly) more detail on all of these is available with
+
+ hg help [command]
+
+Shows the differences between whatever changeset you most recently
+checked out, and your current working directory:
+
+ hg diff
+
+View an annotated version of a source file:
+
+ hg annotate
+
+Get a historical version of a file:
+
+ hg cat
+
+ NB: Most commands accepting a version number want the changeset's
+ version number. "hg cat" is different in that it wants the
+ *file*'s version number.
+
+Unadd a file to the current commit:
+
+ hg forget
+
+List all heads in the current repository:
+
+ hg heads
+
+Undo exactly one (and ONLY one) changeset:
+
+ hg undo
+
+Show the parents of a changeset:
+
+ hg parents
+
+ NB: Changesets have either one or two parent changesets. If your
+ working directory contains the uncommitted results of a merge, then
+ you have two parents. Otherwise, the single parent is the changeset
+ which you most recently checked out.
+
+
_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog
|
Home