Annotation of wikisrc/users/dholland/hgnb.mdwn, revision 1.1
1.1 ! dholland 1: ## Mercurial usage for NetBSD
! 2: (hypothetically assuming the repositories have been converted)
! 3:
! 4: Here are some directions for how one would use Mercurial after a
! 5: NetBSD transition from CVS to Mercurial.
! 6: Most of this is pretty trivial (especially for anyone who's used
! 7: Mercurial before...)
! 8:
! 9: There is a lot of FUD circulating about using a distributed version
! 10: control system, what with talk of "workflows" and "topic branches" and
! 11: other unfamiliar terms.
! 12: Most of this arises from git user communities and git advocates;
! 13: because git is screwy, using git is more complicated than using other
! 14: better designed tools.
! 15: Also, those suffering from Stockholm syndrome with respect to git tend
! 16: to believe that the complexities of git are inherent to distributed
! 17: version control, which is not the case; and many other people have been
! 18: alarmed (or scared, or confused) by things such people have told them.
! 19:
! 20: ### Basic usage
! 21:
! 22: First, NetBSD will go on using a central master repository. There is
! 23: nothing to be gained by changing this; we have the project
! 24: infrastructure to support it, and ultimately there has to be some tree
! 25: somewhere that constitutes the master copy regardless.
! 26:
! 27: Therefore, the basic usage is almost entirely unchanged:
! 28:
! 29: CVS Mercurial
! 30:
! 31: cvs checkout hg clone
! 32: cvs update -dP hg pull && hg update
! 33: cvs -n update hg status
! 34: cvs log file hg log file [or just hg log]
! 35: cvs update -p file hg cat file
! 36: cvs annotate hg annotate
! 37: cvs diff -u hg diff
! 38: cvs add hg add
! 39: cvs rm hg rm
! 40: [no can do] hg cp
! 41: [no can do] hg mv
! 42: cvs commit hg commit && hg push
! 43: cvs tag hg tag
! 44:
! 45: You will notice that CVS's update and commit have been divided into
! 46: two now-separable actions: in Mercurial, pull fetches changes from a
! 47: remote repository but doesn't affect your working tree, and update
! 48: updates your working tree to (by default) the latest new changes.
! 49: Similarly, commit integrates changes from your working tree, but
! 50: locally only; push publishes those changes to the remote repository.
! 51:
! 52: This means that you can commit many times before pushing; this is
! 53: often desirable if you're working on something nontrivial and you want
! 54: to wait until it's ready before shipping it out.
! 55:
! 56: There is one catch, which is that other people can commit (and push to
! 57: the master repository) while you're working. You can mostly avoid
! 58: this, if you haven't committed anything locally yet, by doing "hg pull
! 59: && hg update" before committing, which will merge into your
! 60: uncommitted changes and works exactly like updating before committing
! 61: in CVS. However, if you've committed a number of changes, or someone
! 62: got a new change in right between when you last pulled and when you
! 63: committed, you need to do an explicit merge instead, and then you can
! 64: push.
! 65:
! 66: In the simple case, you do an explicit merge as follows:
! 67: hg pull
! 68: hg merge
! 69: hg commit
! 70:
! 71: When you get a merge conflict, you first need to resolve it (in the
! 72: usual way by editing) and then you must tag it resolved in hg before
! 73: hg will let you commit, like this:
! 74: hg resolve -m file
! 75:
! 76: You can list unresolved conflicts thus:
! 77: hg resolve -l
! 78:
! 79: Note that even with the explicit merge this is almost exactly
! 80: equivalent to the CVS behavior when someone commits ahead of you.
! 81: The chief difference is that because Mercurial does whole-tree
! 82: commits, *any* change ahead of you needs to be merged, not just one
! 83: that touches the same files you've edited.
! 84:
! 85: There is one gotcha, which is that you can't do explicit merges in a
! 86: tree with uncommitted changes. The best way around this is to stash
! 87: your changes:
! 88: hg stash
! 89: hg merge
! 90: ...whatever merge stuff...
! 91: hg unstash
! 92:
! 93: You can also do the merge in another tree; because Mercurial is a
! 94: distributed tool, you can create a temporary copy of your tree, or
! 95: push the changes you need to another tree you already have, do the
! 96: work there, and push the results back. Let's suppose you have two
! 97: trees, "src" and "scratch", where you never keep uncommitted changes
! 98: in "scratch" so it can be used for this kind of thing. Then you can do
! 99: the following (starting at the top of src):
! 100:
! 101: hg push ../scratch
! 102: cd ../scratch
! 103: hg update
! 104: hg merge
! 105: ...whatever merge stuff, including commit...
! 106: cd ../src
! 107: hg pull ../scratch
! 108: hg update
! 109:
! 110: ### Disconnected operation
! 111:
! 112: Mercurial is a distributed system, and works by cloning the entire
! 113: history into each tree you create.
! 114: This has its downsides; but it means that you get disconnected
! 115: operation for free.
! 116: The only operations that need to contact the master repository are
! 117: push, pull, incoming, and outgoing.
! 118:
! 119: ### Some other bits
! 120:
! 121: A commit with no descendents (that is, the most recent commit on any
! 122: line of development) is called a "head".
! 123: You can list these as follows:
! 124: hg heads
! 125:
! 126: This will include commits that have descendents only on other
! 127: branches, e.g. the last commit on a development branch that's been
! 128: merged but not closed. Use "-t" ("topological heads") to hide these.
! 129:
! 130: You can see what "hg pull" and "hg push" are going to do via "hg
! 131: incoming" and "hg outgoing" respectively.
! 132: (FWIW, git can't do this.)
! 133:
! 134: If you interrupt Mercurial (or Mercurial gets interrupted, e.g. by a
! 135: system crash) you want to do this afterwards:
! 136: hg recover
! 137:
! 138: and if you have reason to think the repository might be corrupt you
! 139: can check it like this:
! 140: hg verify
! 141:
! 142: ### Development branches
! 143:
! 144: A development branch is one where you're working on some new feature
! 145: and you expect to merge the branch into the trunk later.
! 146: Unlike in CVS, this is very cheap in Mercurial.
! 147: The following are the operations you need, using "libc13" as an
! 148: example branch name.
! 149:
! 150: Note that even if you're working on something nontrivial that will
! 151: take a number of commits, if you aren't intending to push the changes
! 152: out before they're done you don't need to make a branch and there's
! 153: nothing gained by doing so.
! 154: However, if you expect to be working over a long period of time on a
! 155: major effort (such as the mythical libc version bump), and/or you
! 156: want or expect other developers to contribute or at least test your
! 157: changes before they're done, go ahead and create a branch.
! 158:
! 159: Create a new branch:
! 160:
! 161: cvs update -dP hg pull && hg update (if needed)
! 162: update doc/BRANCHES update doc/BRANCHES (if appropriate)
! 163: cvs commit doc/BRANCHES hg commit doc/BRANCHES (if needed)
! 164: cvs tag libc13-base hg tag libc13-base
! 165: cvs ph'tagn hg branch libc13
! 166: [make first change] [make first change]
! 167: cvs commit hg commit
! 168: hg push
! 169:
! 170: Mercurial warns you that branches are permanent and expensive; this
! 171: warning is aimed at git users who ought to be creating bookmarks
! 172: instead and not something you need to be concerned about.
! 173:
! 174: Check out a new tree on a branch:
! 175: cvs co -P -rlibc13 hg clone [url]
! 176: cd src
! 177: hg update -r libc13
! 178:
! 179: Switch to a new tree on a branch:
! 180: cvs up -dP -A -rlibc13 hg pull (if needed)
! 181: hg update -r libc13
! 182:
! 183: Note that if you have uncommitted changes, Mercurial will balk at
! 184: crossing from one branch to another because it doesn't know how to
! 185: merge them.
! 186: In that case do this:
! 187: hg update -r libc13-base
! 188: [resolve conflicts if needed]
! 189: hg update -r libc13
! 190: [resolve conflicts if needed]
! 191:
! 192: Check which branch you're currently on:
! 193:
! 194: cat CVS/Tag hg branch
! 195:
! 196: See list of branches:
! 197: [no can do reliably] hg branches
! 198:
! 199: Note that unlike with CVS there's no version-control-related reason to
! 200: get a new tree just to work on a branch.
! 201: (Although of course it's still possible to commit to the wrong branch
! 202: by accident.)
! 203: Get a new tree if and only if you want to have a different tree for
! 204: administrative reasons.
! 205:
! 206: Sync your branch with the trunk ("HEAD" in CVS):
! 207:
! 208: cvs ph'tagn hg merge default
! 209: [resolve conflicts] [resolve conflicts]
! 210: cvs commit hg commit
! 211: hg push
! 212:
! 213: When you're done with your branch, in Mercurial you can "close" it so
! 214: it's no longer active.
! 215: This causes it to disappear from some reports, reduces some internal
! 216: management overheads, and prevents accidental commits on it.
! 217:
! 218: [no can do] hg commit --close-branch
! 219:
! 220: Don't forget to update doc/BRANCHES too.
! 221:
! 222: ### Vendor branches
! 223:
! 224: A vendor branch is one where code from a third party is committed in
! 225: unmodified state, so it can be updated easily from upstream later.
! 226:
! 227: Note that in CVS vendor branches are magic (in a bad way); in
! 228: Mercurial we'll just use an ordinary branch. We'll start it from the
! 229: empty revision so it doesn't contain any unwanted rubbish.
! 230:
! 231: To start a new vendor branch for the upstream package "frobozz",
! 232: assuming you've already written frobozz2netbsd if one's needed:
! 233:
! 234: mkdir tmp
! 235: cd tmp
! 236: hg update -r0000
! 237: mkdir external && cd external
! 238: mkdir bsd && cd bsd
! 239: mkdir frobozz && cd frobozz
! 240: tar -xvzf \ tar -xvzf \
! 241: frobozz-1.0.tgz frobozz-1.0.tgz
! 242: mv frobozz-1.0 dist mv frobozz-1.0 dist
! 243: cp .../frobozz2netbsd . cp .../frobozz2netbsd .
! 244: ./frobozz2netbsd ./frobozz2netbsd (if needed)
! 245: cvs import \
! 246: src/distrib/bsd/frobozz \
! 247: FROBOZZ frobozz-1-0
! 248: hg add
! 249: hg branch FROBOZZ
! 250: hg commit
! 251: hg tag frobozz-1-0
! 252: cd ../src
! 253: cvs update -dP
! 254: hg update -r default
! 255: hg merge FROBOZZ
! 256: hg commit
! 257: [hack as needed] [hack as needed]
! 258: cvs commit hg commit
! 259: hg push
! 260: cd ..
! 261: rm -r tmp
! 262:
! 263: Note that in both cases this imports frobozz2netbsd on the branch;
! 264: this seems the most convenient but I'm not sure if it's been our
! 265: standard procedure.
! 266:
! 267: To update "frobozz" to 1.1:
! 268:
! 269: mkdir tmp
! 270: cd tmp
! 271: hg update -rFROBOZZ
! 272: cd external/bsd/frobozz
! 273: tar -xvzf \ tar -xvzf \
! 274: frobozz-1.1.tgz frobozz-1.1.tgz
! 275: rm -r dist
! 276: mv frobozz-1.1 dist mv frobozz-1.1 dist
! 277: ./frobozz2netbsd ./frobozz2netbsd
! 278: cvs import \
! 279: src/distrib/bsd/frobozz \
! 280: FROBOZZ frobozz-1-0
! 281: hg addremove
! 282: hg commit
! 283: hg tag frobozz-1-1
! 284: cd ..
! 285: mkdir tmp2 && cd tmp2
! 286: cvs ph'tagn
! 287: hg update -r default
! 288: hg merge FROBOZZ
! 289: [resolve conflicts] [resolve conflicts]
! 290: cvs commit hg commit
! 291: cd ../src
! 292: cvs update -dP
! 293: [hack as needed] [hack as needed]
! 294: cvs commit hg commit
! 295: hg push
! 296: cd ..
! 297: rm -r tmp tmp2
! 298:
! 299: ### Release branches
! 300:
! 301: A release branch is one that diverges from the main branch and is not
! 302: expected to be merged back into it.
! 303: However, changes from the main branch are (individually) merged into
! 304: it after review.
! 305:
! 306: Creating a release branch in Mercurial is the same as creating a
! 307: feature branch; see above.
! 308: So is checking it out.
! 309: Committing a change to a release branch is no different from
! 310: committing to the default branch or any other branch.
! 311:
! 312: TODO: we should probably use the Mercurial cherrypick extension for at
! 313: least some release branch pullups; I don't know how to do that offhand
! 314: without looking it up.
! 315:
! 316: Tagging a release:
! 317:
! 318: cvs rtag -r netbsd-7 \ hg tag -r netbsd-7 \
! 319: netbsd-7-0-RELEASE netbsd-7-0-RELEASE
! 320:
! 321: Viewing the changes on a branch:
! 322:
! 323: cvs log > file hg log -b netbsd-7
! 324: [page through & curse]
! 325:
! 326: Extracting tarballs:
! 327:
! 328: cd src
! 329: hg export -r \ hg archive -r \
! 330: netbsd-7-0-RELEASE \ netbsd-7-0-RELEASE \
! 331: src .../netbsd-7.0.tar.gz
! 332: mv src netbsd-7.0
! 333: tar -cvzf \
! 334: netbsd-7.0.tar.gz \
! 335: netbsd-7.0
! 336:
! 337: ### Reverting a bad commit
! 338:
! 339: Sometimes somebody commits something that needs to be unwound later.
! 340: In CVS you have to track down each per-file change and undo each one
! 341: separately, then commit them all.
! 342: In Mercurial, because Mercurial has whole-tree commits, you can do it
! 343: with a single command.
! 344:
! 345: cvs update -j1.6 -j1.5 foo.c
! 346: cvs update -j1.9 -j1.8 bar.c
! 347: cvs update -j1.15 -j1.14 baz.c
! 348: hg backout -r 101abcde
! 349: [resolve conflicts] [resolve conflicts]
! 350: cvs commit hg commit
! 351: hg push
! 352:
! 353: Note that apparently if you use hg backout to back out the most recent
! 354: commit, it auto-commits.
! 355: (This seems to me like a UI bug.)
! 356:
! 357: ### Carrying local changes
! 358:
! 359: In CVS you can keep uncommitted changes in your tree indefinitely with
! 360: no ill effects.
! 361: (Or at least, no ill effects until you want to commit other changes to
! 362: the same files, run into merge conflicts, or hit PR 42961.)
! 363:
! 364: In Mercurial having uncommitted changes keeps you from doing explicit
! 365: merges, which you need to do much more often than in CVS.
! 366: There are several ways around this:
! 367:
! 368: * You can stash your uncommitted changes any time you need to merge.
! 369: This works fine but it quickly becomes a nuisance.
! 370: * You can use different trees for hacking and for building the system
! 371: for install, since presumably you only need the local changes in
! 372: the latter case.
! 373: This works fine until you need to shift partially-completed hacking to
! 374: the installable tree, and then becomes painful.
! 375: * You can commit your local changes as "secret" using the evolve
! 376: extension (I recommend reading the docs for the evolve extension);
! 377: then they're committed and can be merged and so on, but won't get
! 378: pushed back to the master repository.
! 379: The downside of this is that you can't readily distribute your local
! 380: changes among your own repositories.
! 381: * You can use the mq patch queue extension and store your local
! 382: changes as patches against the tree; then they can be popped off
! 383: easily for other work.
! 384: The downside of this is that merging stuff into your local changes
! 385: becomes awkward.
! 386: * You can finish your local changes so they can be committed upstream :-)
! 387:
! 388: None of these solutions is perfect, but one or the other of these
! 389: approaches is probably good enough in most cases.
! 390:
! 391: ### Reverting stuff locally
! 392:
! 393: In CVS you can use "cvs update" to pin a subtree down to a specific
! 394: point in history, where it will stay while you update the rest of the
! 395: tree around it.
! 396: (Accidental engagement of this feature is probably as common as
! 397: intentional use...)
! 398:
! 399: There is no direct equivalent in Mercurial.
! 400: However, you can easily alter a file or subtree to roll it back to a
! 401: specific point in history, and then carry the resulting diff as a
! 402: local modification until whatever issue prompted you to do this gets
! 403: sorted out.
! 404:
! 405: To revert to a specific version:
! 406: hg revert -r rev subtree
! 407: To revert to a specific date:
! 408: hg revert -d date subtree
! 409:
! 410:
! 411: ### Other stuff
! 412:
! 413: Have I forgotten anything?
! 414: Email me questions...
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb
![[BACK]](/icons/back.gif){kind=icon}
Return to hgnb.mdwn CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [NetBSD Developer Wiki] / wikisrc / users / dholland