After reading this "multiple checkout mode" in git-checkout.txt, I'm tempted to rewrite it like this. I think the example makes it clearer what I mean. If nobody has any comments, I'm going to send v2 with this (and other comments collected so far) MULTIPLE CHECKOUT MODE ---------------------- Normally a working directory is attached to repository. When "git checkout --to" is used, a new working directory is attached to the current repository. This new working directory is called "linked checkout" as compared to the "main checkout" prepared by "git init" or "git clone". A repository has one main checkout and zero or more linked checkouts. Each linked checkout has a private directory in $GIT_DIR/repos in the main checkout, usually named after the base name of the new working directory, optionally with a number added to make it unique. For example, the command `git checkout --to ../test-next next` running with $GIT_DIR=/path/main may create the directory `$GIT_DIR/repos/test-next` (or `$GIT_DIR/repos/test-next1` if `test-next` is already taken). Within a linked checkout, $GIT_DIR is set to point to this private directory (e.g. `/path/main/repos/test-next` in the example) and $GIT_COMMON_DIR is set to point back to the main checkout's $GIT_DIR (e.g. `/path/main`). Setting is done via a .git file located at the top directory of the linked checkout. Path resolution via `git rev-parse --git-path` would use either $GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, the linked checkout's `$GIT_DIR/HEAD` resolve to `/path/main/repos/test-next/HEAD` (not `/path/main/HEAD` which is the main checkout's HEAD) while `$GIT_DIR/refs/heads/master` would use $GIT_COMMON_DIR and resolve to `/path/main/refs/heads/master`, which is shared across checkouts. See linkgit:gitrepository-layout[5] for more information. The rule of thumb is do not make any assumption about whether a path belongs to $GIT_DIR or $GIT_COMMON_DIR when you need to directly access something inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. -- Duy -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html