# HG changeset patch # User Mike Bayer <mike_mp@zzzcomputing.com> # Date 1330204382 18000 # Sat Feb 25 16:13:02 2012 -0500 # Node ID 2e8820592bd3ac0dc70ebb9713ec34d9cb39ad55 # Parent e58a6d0b80e2cf8e3fb833a495df4603884132f1 Add documentation for branch_bookmark_suffix configuration parameter diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -149,3 +149,37 @@ [git] intree = True + +git.branch_bookmark_suffix +--------------------------- + +hg-git does not convert between Mercurial named branches and git branches as +the two are conceptually different; instead, it uses Mercurial bookmarks to +represent the concept of a git branch. Therefore, when translating an hg repo +over to git, you typically need to create bookmarks to mirror all the named +branches that you'd like to see transferred over to git. The major caveat with +this is that you can't use the same name for your bookmark as that of the +named branch, and furthermore there's no feasible way to rename a branch in +Mercurial. For the use case where one would like to transfer an hg repo over +to git, and maintain the same named branches as are present on the hg side, +the `branch_bookmark_suffix` might be all that's needed. This presents a +string "suffix" that will be recognized on each bookmark name, and stripped +off as the bookmark is translated to a git branch: + + [git] + branch_bookmark_suffix=_bookmark + +Above, if an hg repo had a named branch called `release_6_maintenance`, you could +then link it to a bookmark called `release_6_maintenance_bookmark`. hg-git will then +strip off the `_bookmark` suffix from this bookmark name, and create a git branch +called `release_6_maintenance`. When pulling back from git to hg, the `_bookmark` +suffix is then applied back, if and only if an hg named branch of that name exists. +E.g., when changes to the `release_6_maintenance` branch are checked into git, these +will be placed into the `release_6_maintenance_bookmark` bookmark on hg. But if a +new branch called `release_7_maintenance` were pulled over to hg, and there was +not a `release_7_maintenance` named branch already, the bookmark will be named +`release_7_maintenance` with no usage of the suffix. + +The `branch_bookmark_suffix` option is, like the `authors` option, intended for +migrating legacy hg named branches. Going forward, an hg repo that is to +be linked with a git repo should only use bookmarks for named branching.