checkout: support checking out into a new working directory

"git checkout --to" sets up a new working directory with a .git file
pointing to $GIT_DIR/worktrees/<id>. It then executes "git checkout"
again on the new worktree with the same arguments except "--to" is
taken out. The second checkout execution, which is not contaminated
with any info from the current repository, will actually check out and
everything that normal "git checkout" does.

Helped-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 33ad2adf5ce86119e55f94fa1d29233e8caf4a67..c101575ac237f3760b384ed99da90d685b332061 100644 (file)
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -225,6 +225,13 @@ This means that you can use `git checkout -p` to selectively discard
 edits from your current working tree. See the ``Interactive Mode''
 section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
 
 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=<path>::
+       Check out a branch in a separate working directory at
+       `<path>`. A new working directory is linked to the current
+       repository, sharing everything except working directory
+       specific files such as HEAD, index... See "MULTIPLE WORKING
+       TREES" section for more information.
+

 <branch>::
        Branch to checkout; if it refers to a branch (i.e., a name that,
        when prepended with "refs/heads/", is a valid ref), then that
 <branch>::
        Branch to checkout; if it refers to a branch (i.e., a name that,
        when prepended with "refs/heads/", is a valid ref), then that


@@ -388,6 +395,45 @@ $ git reflog -2 HEAD # or
 $ git log -g -2 HEAD
 ------------
 
 $ git log -g -2 HEAD
 ------------
 

+MULTIPLE WORKING TREES
+----------------------
+
+A git repository can support multiple working trees, allowing you to check
+out more than one branch at a time.  With `git checkout --to` a new working
+tree is associated with the repository.  This new working tree is called a
+"linked working tree" as opposed to the "main working tree" prepared by "git
+init" or "git clone".  A repository has one main working tree (if it's not a
+bare repository) and zero or more linked working trees.
+
+Each linked working tree has a private sub-directory in the repository's
+$GIT_DIR/worktrees directory.  The private sub-directory's name is usually
+the base name of the linked working tree's path, possibly appended with a
+number to make it unique.  For example, when `$GIT_DIR=/path/main/.git` the
+command `git checkout --to /path/other/test-next next` creates the linked
+working tree in `/path/other/test-next` and also creates a
+`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
+if `test-next` is already taken).
+
+Within a linked working tree, $GIT_DIR is set to point to this private
+directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and
+$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR
+(e.g. `/path/main/.git`). These settings are made in a `.git` file located at
+the top directory of the linked working tree.
+
+Path resolution via `git rev-parse --git-path` uses either
+$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the
+linked working tree `git rev-parse --git-path HEAD` returns
+`/path/main/.git/worktrees/test-next/HEAD` (not
+`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git
+rev-parse --git-path refs/heads/master` uses
+$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`,
+since refs are shared across all working trees.
+
+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.
+

 EXAMPLES
 --------
 
 EXAMPLES
 --------
 

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 96354af0d7c6ebbf57c912a9a6445b82e0623ab9..0c2dcfa9cc4f3cc3e3066104ee5a61f0b46fcfde 100644 (file)
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -813,7 +813,8 @@ Git so take care if using Cogito etc.
        If this variable is set to a path, non-worktree files that are
        normally in $GIT_DIR will be taken from this path
        instead. Worktree-specific files such as HEAD or index are
        If this variable is set to a path, non-worktree files that are
        normally in $GIT_DIR will be taken from this path
        instead. Worktree-specific files such as HEAD or index are

-       taken from $GIT_DIR. See linkgit:gitrepository-layout[5] for
+       taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and
+       the section 'MULTIPLE CHECKOUT MODE' in linkgit:checkout[1]

        details. This variable has lower precedence than other path
        variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...
 
        details. This variable has lower precedence than other path
        variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...
 

diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index 2dc5667a0c78fd7ab10dbd47e5e2a6d57a52ae4e..82284506a4b0f321796d7d1b33e5225fe5aba7a2 100644 (file)
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -252,6 +252,13 @@ modules::
        directory is ignored if $GIT_COMMON_DIR is set and
        "$GIT_COMMON_DIR/modules" will be used instead.
 
        directory is ignored if $GIT_COMMON_DIR is set and
        "$GIT_COMMON_DIR/modules" will be used instead.
 

+worktrees::
+       Contains worktree specific information of linked
+       checkouts. Each subdirectory contains the worktree-related
+       part of a linked checkout. This directory is ignored if
+       $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/worktrees" will be
+       used instead.
+

 SEE ALSO
 --------
 linkgit:git-init[1],
 SEE ALSO
 --------
 linkgit:git-init[1],

diff --git a/builtin/checkout.c b/builtin/checkout.c
index 195aca7257fe2a6b52fbee5f21f5ad785be57991..797e14df419aec20f3b9336014973d634fcaaaab 100644 (file)
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -48,6 +48,10 @@ struct checkout_opts {
        const char *prefix;
        struct pathspec pathspec;
        struct tree *source_tree;
        const char *prefix;
        struct pathspec pathspec;
        struct tree *source_tree;

+
+       const char *new_worktree;
+       const char **saved_argv;
+       int new_worktree_mode;

 };
 
 static int post_checkout_hook(struct commit *old, struct commit *new,
 };
 
 static int post_checkout_hook(struct commit *old, struct commit *new,


@@ -249,6 +253,9 @@ static int checkout_paths(const struct checkout_opts *opts,
                die(_("Cannot update paths and switch to branch '%s' at the same time."),
                    opts->new_branch);
 
                die(_("Cannot update paths and switch to branch '%s' at the same time."),
                    opts->new_branch);
 

+       if (opts->new_worktree)
+               die(_("'%s' cannot be used with updating paths"), "--to");
+

        if (opts->patch_mode)
                return run_add_interactive(revision, "--patch=checkout",
                                           &opts->pathspec);
        if (opts->patch_mode)
                return run_add_interactive(revision, "--patch=checkout",
                                           &opts->pathspec);


@@ -484,7 +491,7 @@ static int merge_working_tree(const struct checkout_opts *opts,
                        topts.dir->flags |= DIR_SHOW_IGNORED;
                        setup_standard_excludes(topts.dir);
                }
                        topts.dir->flags |= DIR_SHOW_IGNORED;
                        setup_standard_excludes(topts.dir);
                }

-               tree = parse_tree_indirect(old->commit ?
+               tree = parse_tree_indirect(old->commit && !opts->new_worktree_mode ?

                                           old->commit->object.sha1 :
                                           EMPTY_TREE_SHA1_BIN);
                init_tree_desc(&trees[0], tree->buffer, tree->size);
                                           old->commit->object.sha1 :
                                           EMPTY_TREE_SHA1_BIN);
                init_tree_desc(&trees[0], tree->buffer, tree->size);


@@ -800,7 +807,8 @@ static int switch_branches(const struct checkout_opts *opts,
                return ret;
        }
 
                return ret;
        }
 

-       if (!opts->quiet && !old.path && old.commit && new->commit != old.commit)
+       if (!opts->quiet && !old.path && old.commit &&
+           new->commit != old.commit && !opts->new_worktree_mode)

                orphaned_commit_warning(old.commit, new->commit);
 
        update_refs_for_switch(opts, &old, new);
                orphaned_commit_warning(old.commit, new->commit);
 
        update_refs_for_switch(opts, &old, new);


@@ -810,6 +818,76 @@ static int switch_branches(const struct checkout_opts *opts,
        return ret || writeout_error;
 }
 
        return ret || writeout_error;
 }
 

+static int prepare_linked_checkout(const struct checkout_opts *opts,
+                                  struct branch_info *new)
+{
+       struct strbuf sb_git = STRBUF_INIT, sb_repo = STRBUF_INIT;
+       struct strbuf sb = STRBUF_INIT;
+       const char *path = opts->new_worktree, *name;
+       struct stat st;
+       struct child_process cp;
+       int counter = 0, len;
+
+       if (!new->commit)
+               die(_("no branch specified"));
+       if (file_exists(path))
+               die(_("'%s' already exists"), path);
+
+       len = strlen(path);
+       while (len && is_dir_sep(path[len - 1]))
+               len--;
+
+       for (name = path + len - 1; name > path; name--)
+               if (is_dir_sep(*name)) {
+                       name++;
+                       break;
+               }
+       strbuf_addstr(&sb_repo,
+                     git_path("worktrees/%.*s", (int)(path + len - name), name));
+       len = sb_repo.len;
+       if (safe_create_leading_directories_const(sb_repo.buf))
+               die_errno(_("could not create leading directories of '%s'"),
+                         sb_repo.buf);
+       while (!stat(sb_repo.buf, &st)) {
+               counter++;
+               strbuf_setlen(&sb_repo, len);
+               strbuf_addf(&sb_repo, "%d", counter);
+       }
+       name = strrchr(sb_repo.buf, '/') + 1;
+       if (mkdir(sb_repo.buf, 0777))
+               die_errno(_("could not create directory of '%s'"), sb_repo.buf);
+
+       strbuf_addf(&sb_git, "%s/.git", path);
+       if (safe_create_leading_directories_const(sb_git.buf))
+               die_errno(_("could not create leading directories of '%s'"),
+                         sb_git.buf);
+
+       write_file(sb_git.buf, 1, "gitdir: %s/worktrees/%s\n",
+                  real_path(get_git_common_dir()), name);
+       /*
+        * This is to keep resolve_ref() happy. We need a valid HEAD
+        * or is_git_directory() will reject the directory. Any valid
+        * value would do because this value will be ignored and
+        * replaced at the next (real) checkout.
+        */
+       strbuf_addf(&sb, "%s/HEAD", sb_repo.buf);
+       write_file(sb.buf, 1, "%s\n", sha1_to_hex(new->commit->object.sha1));
+       strbuf_reset(&sb);
+       strbuf_addf(&sb, "%s/commondir", sb_repo.buf);
+       write_file(sb.buf, 1, "../..\n");
+
+       if (!opts->quiet)
+               fprintf_ln(stderr, _("Enter %s (identifier %s)"), path, name);
+
+       setenv("GIT_CHECKOUT_NEW_WORKTREE", "1", 1);
+       setenv(GIT_DIR_ENVIRONMENT, sb_git.buf, 1);
+       setenv(GIT_WORK_TREE_ENVIRONMENT, path, 1);
+       memset(&cp, 0, sizeof(cp));
+       cp.git_cmd = 1;
+       cp.argv = opts->saved_argv;
+       return run_command(&cp);
+}
+

 static int git_checkout_config(const char *var, const char *value, void *cb)
 {
        if (!strcmp(var, "diff.ignoresubmodules")) {
 static int git_checkout_config(const char *var, const char *value, void *cb)
 {
        if (!strcmp(var, "diff.ignoresubmodules")) {


@@ -1071,6 +1149,9 @@ static int checkout_branch(struct checkout_opts *opts,
                die(_("Cannot switch branch to a non-commit '%s'"),
                    new->name);
 
                die(_("Cannot switch branch to a non-commit '%s'"),
                    new->name);
 

+       if (opts->new_worktree)
+               return prepare_linked_checkout(opts, new);
+

        if (!new->commit && opts->new_branch) {
                unsigned char rev[20];
                int flag;
        if (!new->commit && opts->new_branch) {
                unsigned char rev[20];
                int flag;


@@ -1113,6 +1194,8 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
                         N_("do not limit pathspecs to sparse entries only")),
                OPT_HIDDEN_BOOL(0, "guess", &dwim_new_local_branch,
                                N_("second guess 'git checkout no-such-branch'")),
                         N_("do not limit pathspecs to sparse entries only")),
                OPT_HIDDEN_BOOL(0, "guess", &dwim_new_local_branch,
                                N_("second guess 'git checkout no-such-branch'")),

+               OPT_FILENAME(0, "to", &opts.new_worktree,
+                          N_("check a branch out in a separate working directory")),

                OPT_END(),
        };
 
                OPT_END(),
        };
 


@@ -1121,6 +1204,9 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
        opts.overwrite_ignore = 1;
        opts.prefix = prefix;
 
        opts.overwrite_ignore = 1;
        opts.prefix = prefix;
 

+       opts.saved_argv = xmalloc(sizeof(const char *) * (argc + 2));
+       memcpy(opts.saved_argv, argv, sizeof(const char *) * (argc + 1));
+

        gitmodules_config();
        git_config(git_checkout_config, &opts);
 
        gitmodules_config();
        git_config(git_checkout_config, &opts);
 


@@ -1129,6 +1215,11 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
        argc = parse_options(argc, argv, prefix, options, checkout_usage,
                             PARSE_OPT_KEEP_DASHDASH);
 
        argc = parse_options(argc, argv, prefix, options, checkout_usage,
                             PARSE_OPT_KEEP_DASHDASH);
 

+       /* recursive execution from checkout_new_worktree() */
+       opts.new_worktree_mode = getenv("GIT_CHECKOUT_NEW_WORKTREE") != NULL;
+       if (opts.new_worktree_mode)
+               opts.new_worktree = NULL;
+

        if (conflict_style) {
                opts.merge = 1; /* implied */
                git_xmerge_config("merge.conflictstyle", conflict_style, NULL);
        if (conflict_style) {
                opts.merge = 1; /* implied */
                git_xmerge_config("merge.conflictstyle", conflict_style, NULL);

diff --git a/path.c b/path.c
index 94db5016c4bf25c4a029a98ad09b64c8dd0e8430..72eca6dfa52e1c4ef7a942be9ff48f7c701b88ee 100644 (file)
--- a/path.c
+++ b/path.c
@@ -92,7 +92,7 @@ static void replace_dir(struct strbuf *buf, int len, const char *newdir)
 
 static const char *common_list[] = {
        "/branches", "/hooks", "/info", "/logs", "/lost-found", "/modules",
 
 static const char *common_list[] = {
        "/branches", "/hooks", "/info", "/logs", "/lost-found", "/modules",

-       "/objects", "/refs", "/remotes", "/rr-cache", "/svn",
+       "/objects", "/refs", "/remotes", "/worktrees", "/rr-cache", "/svn",

        "config", "gc.pid", "packed-refs", "shallow",
        NULL
 };
        "config", "gc.pid", "packed-refs", "shallow",
        NULL
 };

diff --git a/t/t2025-checkout-to.sh b/t/t2025-checkout-to.sh
new file mode 100755 (executable)
index 0000000..4963415
--- /dev/null
+++ b/t/t2025-checkout-to.sh
@@ -0,0 +1,63 @@
+#!/bin/sh
+
+test_description='test git checkout --to'
+
+. ./test-lib.sh
+
+test_expect_success 'setup' '
+       test_commit init
+'
+
+test_expect_success 'checkout --to not updating paths' '
+       test_must_fail git checkout --to -- init.t
+'
+
+test_expect_success 'checkout --to an existing worktree' '
+       mkdir existing &&
+       test_must_fail git checkout --detach --to existing master
+'
+
+test_expect_success 'checkout --to a new worktree' '
+       git checkout --to here master &&
+       (
+               cd here &&
+               test_cmp ../init.t init.t &&
+               git symbolic-ref HEAD >actual &&
+               echo refs/heads/master >expect &&
+               test_cmp expect actual &&
+               git fsck
+       )
+'
+
+test_expect_success 'checkout --to a new worktree from a subdir' '
+       (
+               mkdir sub &&
+               cd sub &&
+               git checkout --detach --to here master &&
+               cd here &&
+               test_cmp ../../init.t init.t
+       )
+'
+
+test_expect_success 'checkout --to from a linked checkout' '
+       (
+               cd here &&
+               git checkout --to nested-here master &&
+               cd nested-here &&
+               git fsck
+       )
+'
+
+test_expect_success 'checkout --to a new worktree creating new branch' '
+       git checkout --to there -b newmaster master &&
+       (
+               cd there &&
+               test_cmp ../init.t init.t &&
+               git symbolic-ref HEAD >actual &&
+               echo refs/heads/newmaster >expect &&
+               test_cmp expect actual &&
+               git fsck
+       )
+'
+
+test_done