From: Nguyễn Thái Ngọc Duy Date: Wed, 10 Sep 2014 22:41:36 GMT Subject: [PATCH v2 00/32] nd/multiple-work-trees Message-ID: <1410388928-32265-1-git-send-email-pclouds@gmail.com> In-Reply-To: <1409387642-24492-1-git-send-email-pclouds@gmail.com> Changes since last send (diff below): - rename $GIT_DIR/repos to $GIT_DIR/worktrees. update documents and command options accordingly - rewrite the multiple checkout section in git-checkout.txt - reorder some patches to make sure the test suite always pass diff --git a/Documentation/config.txt b/Documentation/config.txt index 57999fa..a85f684 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1211,12 +1211,12 @@ gc.pruneexpire:: "now" may be used to disable this grace period and always prune unreachable objects immediately. -gc.prunereposexpire:: +gc.pruneworktreesexpire:: When 'git gc' is run, it will call - 'prune --repos --expire 3.months.ago'. + 'prune --worktrees --expire 3.months.ago'. Override the grace period with this config variable. The value "now" may be used to disable the grace period and prune - $GIT_DIR/repos immediately. + $GIT_DIR/worktrees immediately. gc.reflogexpire:: gc..reflogexpire:: diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 38c70c5..23f0c80 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -226,7 +226,7 @@ edits from your current working tree. See the ``Interactive Mode'' section of linkgit:git-add[1] to learn how to operate the `--patch` mode. --to=:: - Check out a new branch in a separate working directory at + Check out a branch in a separate working directory at ``. A new working directory is linked to the current repository, sharing everything except working directory specific files such as HEAD, index... See "MULTIPLE CHECKOUT @@ -404,23 +404,50 @@ 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. -All checkouts share the same repository. Linked checkouts see the -repository a bit different from the main checkout. When the checkout -"new" reads the path $GIT_DIR/HEAD for example, the actual path -returned could be $GIT_DIR/repos/new/HEAD. This ensures checkouts -won't step on each other. - -Each linked checkout has a private space in $GIT_DIR/repos, usually -named after the base name of the working directory with a number added -to make it unique. The linked checkout's $GIT_DIR points to this -private space while $GIT_COMMON_DIR points to the main checkout's -$GIT_DIR. These settings are done by "git checkout --to". - -Because in this mode $GIT_DIR becomes a lightweight virtual file -system where a path could be rewritten to some place else, accessing -$GIT_DIR from scripts should use `git rev-parse --git-path` to resolve -a path instead of using it directly unless the path is known to be -private to the working directory. +Each linked checkout has a private directory in $GIT_DIR/worktrees 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/worktrees/test-next` (or `$GIT_DIR/worktrees/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/worktrees/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/worktrees/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. + +When you are done, simply deleting the linked working directory would +suffice. $GIT_DIR/worktrees can be cleaned up using `git prune +--worktrees`, which is part of automated garbage collection. + +After you move a linked working directory to another file system, or +on a file system that does not support hard link, execute any git +command (e.g. `git status`) in the new working directory so that it +could update its location in $GIT_DIR/worktrees and not be +accidentally pruned. + +To stop `git prune --worktrees` from deleting a specific working +directory (e.g. because it's on a portable device), you could add the +file 'locked' to $GIT_DIR/worktrees. For example, if `.git` file of +the new working directory points to `/path/main/worktrees/test-next`, +the full path of the 'locked' file would be +`/path/main/worktrees/test-next/locked`. See +linkgit:gitrepository-layout[5] for details. EXAMPLES -------- diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 50e39ec..a0ea381 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -48,8 +48,8 @@ OPTIONS --expire