view docs/misc/hg-cheatsheet.txt @ 5660:82d686a6b63e

Extended explanation of 'hg diff'.
author gmilos@localhost.localdomain
date Mon Jul 04 14:47:28 2005 +0000 (2005-07-04)
parents f5aaeb5688cf
children e1fbb7fee1d8
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.
278 Repository history
279 ------------------
281 Here are a collection of common commands to get you started:
283 hg history | less
285 shows the history of changesets, starting from the most recent. You
286 want to pipe it to some sort of pager. For more complete details,
288 hg -v history | less
290 will include files modified and full (not just first-line) comments.
292 Additionally, you can see just the tip (head of the current
293 branch) of the repository by typing:
295 hg [-v] tip
298 Moving to a specific changeset
299 ------------------------------
301 The co command lets you change the working version of the repository
302 to a different changeset.
304 hg co [changeset]
306 NB: 'co' is an alias for 'update'
308 This command enables you to rewind the working repository to previous
309 changesets, for example to isolate the changeset in which a bug is
310 introduced.
312 If you try and do a 'co' but have modified files in your repository Hg
313 won't let you unless you ask it explicitly to merge the checked out
314 version into the current tree using the "-m" option. The "-C"
315 (--clean) option will force overwrite any locally modified files.
317 Any commits that are made to non-head changesets will obviously fork
318 the tree, creating a new head. You can see all the heads in a tree with
319 "hg heads".
321 In general, "hg co" does the right thing, although it doesn't
322 currently seem to clean up unused directories that have been created
323 by other checked-out versions. This can confuse the Xen build
324 system. Hg will probably get fixed soon, but in the meantime you can
325 cleanup with "find -depth -type d -print | xargs -r rmdir".
327 You can return to the tip by ommiting an explicit changeset id.
329 The manifest command lets you see the contents of the repository for
330 the current changeset.
332 hg manifest
334 This will print a bunch of records of the form:
336 | 98856c45c35a504bc6da06a62b7787ddfdfd1c8b 644 COPYING
337 | f28971eedc5b54e7a9b26dd18d52992955354981 644
338 | a3575cc4db59e50bbac8a039a0c74f081a8dfc4f 644 Makefile
339 | 7fc869aae2945a9f4626fad96552db3103e61cb9 644 README
340 | ...
342 This lists the hash of each file, its 1-bit 'executable' atribute
343 (either file permission mode 644 or 755), and the file name. So, to
344 determine the files that change across two changesets, you would dump
345 the respective manifests to files, and use diff.
348 Managing changeset tags
349 -----------------------
350 To create a tag to the current changeset:
352 hg tag tagname
354 This will _immediately_ generate a changeset with a change to the file
355 .hgtags in the repository root. The new tag in this file will look
356 something like:
358 | 35159ed4b30538e7a52c60ad0a63f7e9af156e4c tagname
360 and may be used to identify that changeset throughout the repo.
361 Storing tags in this file and generating changesets immediately
362 forces people to merge and keep tags up to date across the repository.
364 Note that tags are resolved by searching .hgtags in each of the
365 repository heads, sequentially, and using the first match. "hg heads"
366 lists the current heads.
368 The "hg tags" command, will lists all the currently valid tags.
371 Hg server and source browser
372 ----------------------------
374 hg serve -p port
376 Launches a web server on the specified port, serving a source browser
377 for the repository. This browser may be used to examine the
378 changeset history, view annotated source files, generate diffs.
379 Additionally "hg pull" may be run against it.
381 Additional useful commands
382 (that probably only need one-line descriptions)
383 -----------------------------------------------
385 (Slightly) more detail on all of these is available with
387 hg help [command]
389 Shows the differences between whatever changeset you most recently
390 checked out, and your current working directory:
392 hg diff
394 View an annotated version of a source file:
396 hg annotate
398 Get a historical version of a file:
400 hg cat
402 NB: Most commands accepting a version number want the changeset's
403 version number. "hg cat" is different in that it wants the
404 *file*'s version number.
406 Unadd a file to the current commit:
408 hg forget
410 List all heads in the current repository:
412 hg heads
414 Undo exactly one (and ONLY one) changeset:
416 hg undo
418 Show the parents of a changeset:
420 hg parents
422 NB: Changesets have either one or two parent changesets. If your
423 working directory contains the uncommitted results of a merge, then
424 you have two parents. Otherwise, the single parent is the changeset
425 which you most recently checked out.