view docs/misc/hg-cheatsheet.txt @ 16715:c5deb251b9dc

Update version to 3.2.0-rc4
author Keir Fraser <>
date Sat Dec 29 17:57:37 2007 +0000 (2007-12-29)
parents a83ac0806d6b
children a2903704c17a
line source
2 Mercurial(hg) Cheatsheet for Xen
3 ================================
5 Written by Andrew Warfield, extended by Michael Fetterman and Ian Pratt
6 June 29, 2005, extended by Grzegorz Milos 04 July 2005.
8 Overview
9 --------
10 The Xen project has moved from BitKeeper to Mercurial for source
11 control. This note aims to provide a quick guide to getting up and
12 running with the new tools as quickly as possible, and is written from
13 the perspective of someone who has been using BK.
15 For a more detailed exposition, see the mecurial tutorial:
18 The Hg manpage is available at:
21 There's also a very useful FAQ that explains the terminology:
24 There's also a good README:
27 Necessary software
28 ------------------
29 Mercurial is available at:
32 You will also need a Python version >= 2.3
34 How Mercurial is different from BK
35 ----------------------------------
36 There are several pertinent differences between hg and bk. This
37 section aims to give an overview of the conceptual differences between
38 the two SCMs -- if you just want examples to get going, skip ahead to
39 "Getting Xen". The key differences are:
41 - No explicit per-file locking. You do not need to explicitly
42 check a file out before editing it.
43 - No notion (currently) of file renames.
44 - A repository can have multiple active heads.
45 - Automatic merge support is currently inferior to BK's.
46 - No graphical tools.
47 - No per-file revision history, only per-changeset (we never really used this anyhow)
48 - Hg repositories tend to be rather bigger than Bk ones, but Hg does seem faster.
50 Mercurial is based on the notion of changesets as complete, immutable,
51 versions of the repository. You make changes to a working version of
52 the repository that is based on a particular changeset. When you
53 commit, you will generate a new child changeset with whatever changes
54 you choose to apply.
56 A major difference between Hg and BK is that you aren't forced to
57 resolve conflicts immediately: BK forced you to resolve conflicts
58 immediately on any merge, and it then immediately created a changeset
59 with those conflicts' resolutions. Frequently, you then had to add
60 yet another changeset to fixup the things for which the automatic
61 merge yielded bad results. Hg puts the results of the merge into your
62 work directory, and remembers what you merged with (so that it can
63 later record both of the merge parents, if you decide to make a
64 changeset), but it doesn't immediately create a changeset.
66 A further feature of Hg is that it allows a repository to have
67 multiple heads. This means that you can have changesets with no common
68 descendent in one repository -- something BK won't allow. This is
69 actually pretty neat. For example, it would in principle enable you to
70 have both the 2.0-testing and unstable trees in a single
71 repository. We shyed away from doing this as we thought the risk of
72 commiting to the wrong head was too great.
74 One slightly confusing aspect of Hg is that many of the commands have
75 aliases, and hence when looking things up in the man page its not
76 always obvious what the underlying command is. For example 'co' is
77 actually an alias for the 'update' command, but 'co' seems to make
78 more sense, at least to RCS refugees like me.
81 Getting Xen
82 -----------
84 The URL for the mainline Xen mercurial respository is:
87 (similarly for xen-2.0 and xen-2.0-testing)
89 You can point a browser and this and use Hg's web interface to view
90 revision history, or use it as the nominated source when issuing
91 "hg init" or "hg pull" commands.
93 However, to avoid taxing the Mercurial server with a complete pull of
94 the Xen repository, it is best to download a tarball of a seed
95 repository from:
99 (or copy from /usr/groups/netos/html/xen/downloads/xen-unstable.hg.tar.gz)
101 Untar the repository on your disk, cd into it, and then pull the most
102 recent changes:
104 hg pull -u
106 By default hg does not automatically checkout ('update') files from
107 the repository as used to happen with bk. The above is equivalent to
108 "hg pull; hg co"
110 The repository parent is stored in a repository configuration file,
111 .hg/hgrc, from the repository root. If you look at this file, you
112 will see:
114 | [paths]
115 | default =
117 "default" specifies the appropriate parent repository for hg to pull
118 from. Hg allows you to pull additional repositories, for instance if
119 you want to work between unstable and testing concurrently.
121 The command "hg pull" simply adds changesets to your repository,
122 without any merging of any kind. "hg pull -u" implies merging with
123 the current state of your working directory. If you weren't already
124 "updated" to your local repository's tip, you might be surprised to
125 find yourself merging the results of the pull with a non-tip node in
126 your local repository.
129 Revision History
130 ----------------
132 You can view the repository revision history with:
134 hg history
136 In practice, you'll probably want to use pipe the output through
137 'head' or 'more' as it prints the entire history.
139 Looking at the first few lines of output, you can see the changeset at
140 the head of the current branch, known as the 'tip' (the tip is
141 automatically given a special tag to make it easy to refer to):
143 | changeset: 5599:6cbf9ec05cd9e05c0c46a85df7fc00262633cd3d
144 | tag: tip
145 | user:
146 | date: Tue Jun 28 18:47:14 2005
147 | summary: bitkeeper revision 1.1768 (42c18d2259NPELcGV7ohyZNh72ufSw)
149 By default, Hg just shows the first line of the changset comments. You
150 can find further information with "hg -v history".
152 The changeset identifier has two parts, a _local_ monotonically
153 increasing changeset id, 5599 above, and a _global_ hash, which
154 follows the colon on the changeset line. The hash uniquely identifies
155 the changeset and its lineage back to the root of the changeset tree
156 -- it is useful for distributed management and so on. However, as it
157 is a bit unruly, the local id will allow you to work easily with the
158 local repo. Hg commands will take either identifier. Additionally, a
159 tags mechanism lets you give common names to specific changesets.
161 You should always use the global hash when referring to versions of
162 the mainline Xen respoitory. With Bk you could often get away with
163 using the shortform version, but with Hg the local ids are pretty much
164 guaranteed to be different.
167 Creating a child repository from an existing repository
168 -------------------------------------------------------
169 If you wanted to create additional local child repositories,
171 hg init [path or url]
173 is effectively equivalent to bk clone. The major difference is that
174 it should be run from the root of your new repository. So:
176 bk clone /foo/bar
178 would be replaced with:
180 mkdir bar
181 cd bar
182 hg init /foo/bar
184 NB: newer version of Hg support a 'clone' command that works in the
185 same manner as bk.
187 Editing files
188 -------------
190 Normal edits may be made in place. File creation needs explicit
191 marking, though deletes should be picked up automatically
193 creation:
195 touch a.txt (or otherwise created a file)
196 hg add a.txt
198 You can see what has changed using:
200 hg status
202 | C foo/foo.c
203 | R foo/bar.c
204 | ? a.txt
206 This shows that in the current repo, foo.c has been changed, bar.c has
207 been deleted, and a.txt is new, but has not been added. '?' changes
208 to 'A' after "hg add a.txt". There is a .hgignore file which contains
209 regexps of files that should be ignored when scanning for new
210 files. We try to ensure that all the generated files in a build are
211 covered by the regexps.
213 You can add all the new files in a repository with "hg addremove". If
214 you discover that you've added a file you didn't want, you can remove
215 it from the list of files to be included in the next commit using
216 "hg forget".
218 Committing changes
219 -----------------
221 After you've checked that hg knows about any new files you've created,
222 you probably want to see a diff of what you're about to commit. You
223 can do this with:
225 hg diff
227 Once you're happy with what you have, invoke:
229 hg commit
231 This will pop up an editor with a list of files to be committed to the
232 repository. It will look vaguely like this:
234 |
235 | HG: manifest hash 6397b04bd5c2a992482d973b685a7e5e498788e7
236 | HG: changed doc/thesis/new.tex
237 | HG: removed doc/2005-hotdep-protection/paper.tex
239 Your comments can go anywhere in this file. The first line is the
240 most important, as it will show as the changeset description in
241 non-verbose-mode history listings.
243 You can do commits without the editor and of partial sets of files
244 using command-line switches. See:
246 hg help commit
248 You can use the -A (--addremove) flag to commit e.g. "hg -A commit" to
249 ask mercurial to scan the tree looking for newly created files to add
250 in to the changeset. This avoids having to explicitly use "hg add",
251 but you probably want to be careful of adding any new generated files
252 too.
255 Generating a patch
256 ------------------
257 Generating a patch is easy,
259 hg export [changeset]
261 will generate a patch describing the diff between that changeset and
262 its parent.
264 To generate a patch between two specified revisions use:
265 hg diff -r A -r B [files]
266 NB: BK syntax -rA..B isn't supported by Hg.
269 Pushing changesets to a parent repository
270 -----------------------------------------
272 hg push
274 Pushes changes up to a parent. You can't push if you pulled the
275 repository off the web interface. In fact, you can currently only push
276 to an ssh target -- filesystem drectory targets don't work, but this
277 will be fixed soon.
278 For now it is possible to set up assymetric pull/push paths. Pulls can
279 be done via web interface while pushes via ssh. Example of .hg/hgrc config
280 file:
281 | [paths]
282 | default = http://your.server/repository_name
283 | default-push = ssh://[username@]your.server//repository_location
286 Repository history
287 ------------------
289 Here are a collection of common commands to get you started:
291 hg history | less
293 shows the history of changesets, starting from the most recent. You
294 want to pipe it to some sort of pager. For more complete details,
296 hg -v history | less
298 will include files modified and full (not just first-line) comments.
300 Additionally, you can see just the tip (head of the current
301 branch) of the repository by typing:
303 hg [-v] tip
306 Moving to a specific changeset
307 ------------------------------
309 The co command lets you change the working version of the repository
310 to a different changeset.
312 hg co [changeset]
314 NB: 'co' is an alias for 'update'
316 This command enables you to rewind the working repository to previous
317 changesets, for example to isolate the changeset in which a bug is
318 introduced.
320 If you try and do a 'co' but have modified files in your repository Hg
321 won't let you unless you ask it explicitly to merge the checked out
322 version into the current tree using the "-m" option. The "-C"
323 (--clean) option will force overwrite any locally modified files.
325 Any commits that are made to non-head changesets will obviously fork
326 the tree, creating a new head. You can see all the heads in a tree with
327 "hg heads".
329 In general, "hg co" does the right thing, although it doesn't
330 currently seem to clean up unused directories that have been created
331 by other checked-out versions. This can confuse the Xen build
332 system. Hg will probably get fixed soon, but in the meantime you can
333 cleanup with "find -depth -type d -print | xargs -r rmdir".
335 You can return to the tip by ommiting an explicit changeset id.
337 The manifest command lets you see the contents of the repository for
338 the current changeset.
340 hg manifest
342 This will print a bunch of records of the form:
344 | 98856c45c35a504bc6da06a62b7787ddfdfd1c8b 644 COPYING
345 | f28971eedc5b54e7a9b26dd18d52992955354981 644
346 | a3575cc4db59e50bbac8a039a0c74f081a8dfc4f 644 Makefile
347 | 7fc869aae2945a9f4626fad96552db3103e61cb9 644 README
348 | ...
350 This lists the hash of each file, its 1-bit 'executable' atribute
351 (either file permission mode 644 or 755), and the file name. So, to
352 determine the files that change across two changesets, you would dump
353 the respective manifests to files, and use diff.
356 Managing changeset tags
357 -----------------------
358 To create a tag to the current changeset:
360 hg tag tagname
362 This will _immediately_ generate a changeset with a change to the file
363 .hgtags in the repository root. The new tag in this file will look
364 something like:
366 | 35159ed4b30538e7a52c60ad0a63f7e9af156e4c tagname
368 and may be used to identify that changeset throughout the repo.
369 Storing tags in this file and generating changesets immediately
370 forces people to merge and keep tags up to date across the repository.
372 Note that tags are resolved by searching .hgtags in each of the
373 repository heads, sequentially, and using the first match. "hg heads"
374 lists the current heads.
376 The "hg tags" command, will lists all the currently valid tags.
379 Hg server and source browser
380 ----------------------------
382 hg serve -p port
384 Launches a web server on the specified port, serving a source browser
385 for the repository. This browser may be used to examine the
386 changeset history, view annotated source files, generate diffs.
387 Additionally "hg pull" may be run against it.
389 Additional useful commands
390 (that probably only need one-line descriptions)
391 -----------------------------------------------
393 (Slightly) more detail on all of these is available with
395 hg help [command]
397 Shows the differences between whatever changeset you most recently
398 checked out, and your current working directory:
400 hg diff
402 View an annotated version of a source file:
404 hg annotate
406 Get a historical version of a file:
408 hg cat
410 NB: Most commands accepting a version number want the changeset's
411 version number. "hg cat" is different in that it wants the
412 *file*'s version number.
414 Unadd a file to the current commit:
416 hg forget
418 List all heads in the current repository:
420 hg heads
422 Undo exactly one (and ONLY one) changeset:
424 hg undo
426 Show the parents of a changeset:
428 hg parents
430 NB: Changesets have either one or two parent changesets. If your
431 working directory contains the uncommitted results of a merge, then
432 you have two parents. Otherwise, the single parent is the changeset
433 which you most recently checked out.
435 Show the revision history for a single file
437 hg [-v] log <filename>