view docs/misc/hg-cheatsheet.txt @ 5669:ff5d7ccd8d69

No changes from me.
date Tue Jul 05 08:47:55 2005 +0000 (2005-07-05)
parents 8bd2e8933277
children b237f032cee1 32fb371cc283 707fcf42a5ae
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 Untar the repository on your disk, cd into it, and then pull the most
100 recent changes:
102 hg pull -u
104 By default hg does not automatically checkout ('update') files from
105 the repository as used to happen with bk. The above is equivalent to
106 "hg pull; hg co"
108 The repository parent is stored in a repository configuration file,
109 .hg/hgrc, from the repository root. If you look at this file, you
110 will see:
112 | [paths]
113 | default =
115 "default" specifies the appropriate parent repository for hg to pull
116 from. Hg allows you to pull additional repositories, for instance if
117 you want to work between unstable and testing concurrently.
119 The command "hg pull" simply adds changesets to your repository,
120 without any merging of any kind. "hg pull -u" implies merging with
121 the current state of your working directory. If you weren't already
122 "updated" to your local repository's tip, you might be surprised to
123 find yourself merging the results of the pull with a non-tip node in
124 your local repository.
127 Revision History
128 ----------------
130 You can view the repository revision history with:
132 hg history
134 In practice, you'll probably want to use pipe the output through
135 'head' or 'more' as it prints the entire history.
137 Looking at the first few lines of output, you can see the changeset at
138 the head of the current branch, known as the 'tip' (the tip is
139 automatically given a special tag to make it easy to refer to):
141 | changeset: 5599:6cbf9ec05cd9e05c0c46a85df7fc00262633cd3d
142 | tag: tip
143 | user:
144 | date: Tue Jun 28 18:47:14 2005
145 | summary: bitkeeper revision 1.1768 (42c18d2259NPELcGV7ohyZNh72ufSw)
147 By default, Hg just shows the first line of the changset comments. You
148 can find further information with "hg -v history".
150 The changeset identifier has two parts, a _local_ monotonically
151 increasing changeset id, 5599 above, and a _global_ hash, which
152 follows the colon on the changeset line. The hash uniquely identifies
153 the changeset and its lineage back to the root of the changeset tree
154 -- it is useful for distributed management and so on. However, as it
155 is a bit unruly, the local id will allow you to work easily with the
156 local repo. Hg commands will take either identifier. Additionally, a
157 tags mechanism lets you give common names to specific changesets.
159 You should always use the global hash when referring to versions of
160 the mainline Xen respoitory. With Bk you could often get away with
161 using the shortform version, but with Hg the local ids are pretty much
162 guaranteed to be different.
165 Creating a child repository from an existing repository
166 -------------------------------------------------------
167 If you wanted to create additional local child repositories,
169 hg init [path or url]
171 is effectively equivalent to bk clone. The major difference is that
172 it should be run from the root of your new repository. So:
174 bk clone /foo/bar
176 would be replaced with:
178 mkdir bar
179 cd bar
180 hg init /foo/bar
182 NB: newer version of Hg support a 'clone' command that works in the
183 same manner as bk.
185 Editing files
186 -------------
188 Normal edits may be made in place. File creation needs explicit
189 marking, though deletes should be picked up automatically
191 creation:
193 touch a.txt (or otherwise created a file)
194 hg add a.txt
196 You can see what has changed using:
198 hg status
200 | C foo/foo.c
201 | R foo/bar.c
202 | ? a.txt
204 This shows that in the current repo, foo.c has been changed, bar.c has
205 been deleted, and a.txt is new, but has not been added. '?' changes
206 to 'A' after "hg add a.txt". There is a .hgignore file which contains
207 regexps of files that should be ignored when scanning for new
208 files. We try to ensure that all the generated files in a build are
209 covered by the regexps.
211 You can add all the new files in a repository with "hg addremove". If
212 you discover that you've added a file you didn't want, you can remove
213 it from the list of files to be included in the next commit using
214 "hg forget".
216 Committing changes
217 -----------------
219 After you've checked that hg knows about any new files you've created,
220 you probably want to see a diff of what you're about to commit. You
221 can do this with:
223 hg diff
225 Once you're happy with what you have, invoke:
227 hg commit
229 This will pop up an editor with a list of files to be committed to the
230 repository. It will look vaguely like this:
232 |
233 | HG: manifest hash 6397b04bd5c2a992482d973b685a7e5e498788e7
234 | HG: changed doc/thesis/new.tex
235 | HG: removed doc/2005-hotdep-protection/paper.tex
237 Your comments can go anywhere in this file. The first line is the
238 most important, as it will show as the changeset description in
239 non-verbose-mode history listings.
241 You can do commits without the editor and of partial sets of files
242 using command-line switches. See:
244 hg help commit
246 You can use the -A (--addremove) flag to commit e.g. "hg -A commit" to
247 ask mercurial to scan the tree looking for newly created files to add
248 in to the changeset. This avoids having to explicitly use "hg add",
249 but you probably want to be careful of adding any new generated files
250 too.
253 Generating a patch
254 ------------------
255 Generating a patch is easy,
257 hg export [changeset]
259 will generate a patch describing the diff between that changeset and
260 its parent.
262 To generate a patch between two specified revisions use:
263 hg diff -r A -r B [files]
264 NB: BK syntax -rA..B isn't supported by Hg.
267 Pushing changesets to a parent repository
268 -----------------------------------------
270 hg push
272 Pushes changes up to a parent. You can't push if you pulled the
273 repository off the web interface. In fact, you can currently only push
274 to an ssh target -- filesystem drectory targets don't work, but this
275 will be fixed soon.
276 For now it is possible to set up assymetric pull/push paths. Pulls can
277 be done via web interface while pushes via ssh. Example of .hg/hgrc config
278 file:
279 | [paths]
280 | default = http://your.server/repository_name
281 | default-push = ssh://[username@]your.server//repository_location
284 Repository history
285 ------------------
287 Here are a collection of common commands to get you started:
289 hg history | less
291 shows the history of changesets, starting from the most recent. You
292 want to pipe it to some sort of pager. For more complete details,
294 hg -v history | less
296 will include files modified and full (not just first-line) comments.
298 Additionally, you can see just the tip (head of the current
299 branch) of the repository by typing:
301 hg [-v] tip
304 Moving to a specific changeset
305 ------------------------------
307 The co command lets you change the working version of the repository
308 to a different changeset.
310 hg co [changeset]
312 NB: 'co' is an alias for 'update'
314 This command enables you to rewind the working repository to previous
315 changesets, for example to isolate the changeset in which a bug is
316 introduced.
318 If you try and do a 'co' but have modified files in your repository Hg
319 won't let you unless you ask it explicitly to merge the checked out
320 version into the current tree using the "-m" option. The "-C"
321 (--clean) option will force overwrite any locally modified files.
323 Any commits that are made to non-head changesets will obviously fork
324 the tree, creating a new head. You can see all the heads in a tree with
325 "hg heads".
327 In general, "hg co" does the right thing, although it doesn't
328 currently seem to clean up unused directories that have been created
329 by other checked-out versions. This can confuse the Xen build
330 system. Hg will probably get fixed soon, but in the meantime you can
331 cleanup with "find -depth -type d -print | xargs -r rmdir".
333 You can return to the tip by ommiting an explicit changeset id.
335 The manifest command lets you see the contents of the repository for
336 the current changeset.
338 hg manifest
340 This will print a bunch of records of the form:
342 | 98856c45c35a504bc6da06a62b7787ddfdfd1c8b 644 COPYING
343 | f28971eedc5b54e7a9b26dd18d52992955354981 644
344 | a3575cc4db59e50bbac8a039a0c74f081a8dfc4f 644 Makefile
345 | 7fc869aae2945a9f4626fad96552db3103e61cb9 644 README
346 | ...
348 This lists the hash of each file, its 1-bit 'executable' atribute
349 (either file permission mode 644 or 755), and the file name. So, to
350 determine the files that change across two changesets, you would dump
351 the respective manifests to files, and use diff.
354 Managing changeset tags
355 -----------------------
356 To create a tag to the current changeset:
358 hg tag tagname
360 This will _immediately_ generate a changeset with a change to the file
361 .hgtags in the repository root. The new tag in this file will look
362 something like:
364 | 35159ed4b30538e7a52c60ad0a63f7e9af156e4c tagname
366 and may be used to identify that changeset throughout the repo.
367 Storing tags in this file and generating changesets immediately
368 forces people to merge and keep tags up to date across the repository.
370 Note that tags are resolved by searching .hgtags in each of the
371 repository heads, sequentially, and using the first match. "hg heads"
372 lists the current heads.
374 The "hg tags" command, will lists all the currently valid tags.
377 Hg server and source browser
378 ----------------------------
380 hg serve -p port
382 Launches a web server on the specified port, serving a source browser
383 for the repository. This browser may be used to examine the
384 changeset history, view annotated source files, generate diffs.
385 Additionally "hg pull" may be run against it.
387 Additional useful commands
388 (that probably only need one-line descriptions)
389 -----------------------------------------------
391 (Slightly) more detail on all of these is available with
393 hg help [command]
395 Shows the differences between whatever changeset you most recently
396 checked out, and your current working directory:
398 hg diff
400 View an annotated version of a source file:
402 hg annotate
404 Get a historical version of a file:
406 hg cat
408 NB: Most commands accepting a version number want the changeset's
409 version number. "hg cat" is different in that it wants the
410 *file*'s version number.
412 Unadd a file to the current commit:
414 hg forget
416 List all heads in the current repository:
418 hg heads
420 Undo exactly one (and ONLY one) changeset:
422 hg undo
424 Show the parents of a changeset:
426 hg parents
428 NB: Changesets have either one or two parent changesets. If your
429 working directory contains the uncommitted results of a merge, then
430 you have two parents. Otherwise, the single parent is the changeset
431 which you most recently checked out.