From: Junio C Hamano <gitster@pobox•com>
To: Marc Branchaud <marcnarc@xiplink•com>
Cc: Duy Nguyen <pclouds@gmail•com>,
Git Mailing List <git@vger•kernel.org>,
Philip Oakley <philipoakley@iee•org>
Subject: Re: [PATCH 22/32] checkout: support checking out into a new working directory
Date: Tue, 02 Sep 2014 10:33:02 -0700 [thread overview]
Message-ID: <xmqqfvga2ai9.fsf@gitster.dls.corp.google.com> (raw)
In-Reply-To: <5405D983.3050707@xiplink.com> (Marc Branchaud's message of "Tue, 02 Sep 2014 10:51:47 -0400")
Marc Branchaud <marcnarc@xiplink•com> writes:
> On 14-09-02 08:27 AM, Duy Nguyen wrote:
>> 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)
>
> Overall I think focusing on the word "checkout" for this feature makes the
> documentation confusing. It's also not a "mode" but just another git
> feature. Since this is all about multiple working directories (the phrase is
> actually "working tree" in the existing docs) we should just stick to that
> rather than introduce new terminology.
>
> Finally, a bit of bikeshedding, but I think "$GIT_DIR/repos" is also an
> unfortunate choice and that "$GIT_DIR/worktrees" would be better.
I tried to stay away from bikeshedding, but a good phrasing is
important. I think $GIT_DIR/worktrees captures what they are trying
to represent better in that they are not storing repository
information, but they are about storing per-worktree state.
> So I suggest the following for the new section:
>
>
> 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.
>
>
> M.
next prev parent reply other threads:[~2014-09-02 17:33 UTC|newest]
Thread overview: 134+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-08-30 8:33 [PATCH 00/32] nd/multiple-work-trees cleanup Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 01/32] path.c: make get_pathname() return strbuf instead of static buffer Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 02/32] path.c: make get_pathname() call sites return const char * Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 03/32] git_snpath(): retire and replace with strbuf_git_path() Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 04/32] path.c: rename vsnpath() to do_git_path() Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 05/32] path.c: group git_path(), git_pathdup() and strbuf_git_path() together Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 06/32] git_path(): be aware of file relocation in $GIT_DIR Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 07/32] *.sh: respect $GIT_INDEX_FILE Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 08/32] reflog: avoid constructing .lock path with git_path Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 09/32] fast-import: use git_path() for accessing .git dir instead of get_git_dir() Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 10/32] commit: use SEQ_DIR instead of hardcoding "sequencer" Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 11/32] $GIT_COMMON_DIR: a new environment variable Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 12/32] git-sh-setup.sh: use rev-parse --git-path to get $GIT_DIR/objects Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 13/32] *.sh: avoid hardcoding $GIT_DIR/hooks/ Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 14/32] git-stash: avoid hardcoding $GIT_DIR/logs/ Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 15/32] setup.c: convert is_git_directory() to use strbuf Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 16/32] setup.c: detect $GIT_COMMON_DIR in is_git_directory() Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 17/32] setup.c: convert check_repository_format_gently to use strbuf Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 18/32] setup.c: detect $GIT_COMMON_DIR check_repository_format_gently() Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 19/32] setup.c: support multi-checkout repo setup Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 20/32] wrapper.c: wrapper to open a file, fprintf then close Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 21/32] use new wrapper write_file() for simple file writing Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 22/32] checkout: support checking out into a new working directory Nguyễn Thái Ngọc Duy
2014-08-30 20:50 ` Philip Oakley
2014-08-31 4:49 ` Duy Nguyen
2014-08-31 4:52 ` Duy Nguyen
2014-08-31 11:08 ` Philip Oakley
2014-09-02 12:27 ` Duy Nguyen
2014-09-02 14:51 ` Marc Branchaud
2014-09-02 17:33 ` Junio C Hamano [this message]
2014-09-04 14:19 ` Duy Nguyen
2014-09-08 10:52 ` Duy Nguyen
2014-09-08 14:06 ` Marc Branchaud
2014-09-05 3:26 ` Scott Schmit
2014-09-05 13:42 ` Duy Nguyen
2014-08-30 8:33 ` [PATCH 23/32] checkout: clean up half-prepared directories in --to mode Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 24/32] checkout: reject if the branch is already checked out elsewhere Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 25/32] prune: strategies for linked checkouts Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 26/32] gc: style change -- no SP before closing parenthesis Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 27/32] gc: factor out gc.pruneexpire parsing code Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 28/32] gc: support prune --repos Nguyễn Thái Ngọc Duy
2014-08-30 8:33 ` [PATCH 29/32] count-objects: report unused files in $GIT_DIR/repos/ Nguyễn Thái Ngọc Duy
2014-08-30 8:34 ` [PATCH 30/32] git_path(): keep "info/sparse-checkout" per work-tree Nguyễn Thái Ngọc Duy
2014-08-30 8:34 ` [PATCH 31/32] checkout: don't require a work tree when checking out into a new one Nguyễn Thái Ngọc Duy
2014-08-30 8:34 ` [PATCH 32/32] t2025: add a test to make sure grafts is working from a linked checkout Nguyễn Thái Ngọc Duy
2014-08-30 11:11 ` [PATCH 00/32] nd/multiple-work-trees cleanup Eric Sunshine
2014-08-30 11:14 ` Duy Nguyen
2014-09-02 17:29 ` Junio C Hamano
2014-09-10 22:41 ` [PATCH v2 00/32] nd/multiple-work-trees Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 01/32] path.c: make get_pathname() return strbuf instead of static buffer Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 02/32] path.c: make get_pathname() call sites return const char * Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 03/32] git_snpath(): retire and replace with strbuf_git_path() Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 04/32] path.c: rename vsnpath() to do_git_path() Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 05/32] path.c: group git_path(), git_pathdup() and strbuf_git_path() together Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 06/32] git_path(): be aware of file relocation in $GIT_DIR Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 07/32] *.sh: respect $GIT_INDEX_FILE Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 08/32] reflog: avoid constructing .lock path with git_path Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 09/32] fast-import: use git_path() for accessing .git dir instead of get_git_dir() Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 10/32] commit: use SEQ_DIR instead of hardcoding "sequencer" Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 11/32] $GIT_COMMON_DIR: a new environment variable Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 12/32] git-sh-setup.sh: use rev-parse --git-path to get $GIT_DIR/objects Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 13/32] *.sh: avoid hardcoding $GIT_DIR/hooks/ Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 14/32] git-stash: avoid hardcoding $GIT_DIR/logs/ Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 15/32] setup.c: convert is_git_directory() to use strbuf Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 16/32] setup.c: detect $GIT_COMMON_DIR in is_git_directory() Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 17/32] setup.c: convert check_repository_format_gently to use strbuf Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 18/32] setup.c: detect $GIT_COMMON_DIR check_repository_format_gently() Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 19/32] setup.c: support multi-checkout repo setup Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 20/32] wrapper.c: wrapper to open a file, fprintf then close Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 21/32] use new wrapper write_file() for simple file writing Nguyễn Thái Ngọc Duy
2014-09-10 22:41 ` [PATCH v2 22/32] checkout: support checking out into a new working directory Nguyễn Thái Ngọc Duy
2014-09-11 15:02 ` Marc Branchaud
2014-09-21 2:41 ` Duy Nguyen
2014-09-21 3:10 ` Eric Sunshine
2014-09-21 9:50 ` Duy Nguyen
2014-09-22 21:00 ` Marc Branchaud
2014-09-22 23:01 ` Eric Sunshine
2014-09-10 22:41 ` [PATCH v2 23/32] prune: strategies for linked checkouts Nguyễn Thái Ngọc Duy
2014-09-11 15:36 ` Marc Branchaud
2014-09-12 3:06 ` Eric Sunshine
2014-09-12 19:08 ` Marc Branchaud
2014-09-21 2:54 ` Duy Nguyen
2014-09-21 3:01 ` Eric Sunshine
2014-09-21 10:29 ` Duy Nguyen
2014-09-22 21:06 ` Marc Branchaud
2014-09-22 22:19 ` Eric Sunshine
2014-09-10 22:42 ` [PATCH v2 24/32] checkout: reject if the branch is already checked out elsewhere Nguyễn Thái Ngọc Duy
2014-09-10 22:42 ` [PATCH v2 25/32] checkout: clean up half-prepared directories in --to mode Nguyễn Thái Ngọc Duy
2014-09-10 22:42 ` [PATCH v2 26/32] gc: style change -- no SP before closing parenthesis Nguyễn Thái Ngọc Duy
2014-09-10 22:42 ` [PATCH v2 27/32] gc: factor out gc.pruneexpire parsing code Nguyễn Thái Ngọc Duy
2014-09-10 22:42 ` [PATCH v2 28/32] gc: support prune --worktrees Nguyễn Thái Ngọc Duy
2014-09-21 10:43 ` Duy Nguyen
2014-09-22 21:06 ` Marc Branchaud
2014-09-10 22:42 ` [PATCH v2 29/32] count-objects: report unused files in $GIT_DIR/worktrees/ Nguyễn Thái Ngọc Duy
2014-09-10 22:42 ` [PATCH v2 30/32] git_path(): keep "info/sparse-checkout" per work-tree Nguyễn Thái Ngọc Duy
2014-09-10 22:42 ` [PATCH v2 31/32] checkout: don't require a work tree when checking out into a new one Nguyễn Thái Ngọc Duy
2014-09-10 22:42 ` [PATCH v2 32/32] t2025: add a test to make sure grafts is working from a linked checkout Nguyễn Thái Ngọc Duy
2014-09-25 21:20 ` [PATCH v2 00/32] nd/multiple-work-trees Junio C Hamano
2014-09-28 1:22 ` [PATCH v3 " Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 01/32] path.c: make get_pathname() return strbuf instead of static buffer Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 02/32] path.c: make get_pathname() call sites return const char * Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 03/32] git_snpath(): retire and replace with strbuf_git_path() Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 04/32] path.c: rename vsnpath() to do_git_path() Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 05/32] path.c: group git_path(), git_pathdup() and strbuf_git_path() together Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 06/32] git_path(): be aware of file relocation in $GIT_DIR Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 07/32] *.sh: respect $GIT_INDEX_FILE Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 08/32] reflog: avoid constructing .lock path with git_path Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 09/32] fast-import: use git_path() for accessing .git dir instead of get_git_dir() Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 10/32] commit: use SEQ_DIR instead of hardcoding "sequencer" Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 11/32] $GIT_COMMON_DIR: a new environment variable Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 12/32] git-sh-setup.sh: use rev-parse --git-path to get $GIT_DIR/objects Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 13/32] *.sh: avoid hardcoding $GIT_DIR/hooks/ Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 14/32] git-stash: avoid hardcoding $GIT_DIR/logs/ Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 15/32] setup.c: convert is_git_directory() to use strbuf Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 16/32] setup.c: detect $GIT_COMMON_DIR in is_git_directory() Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 17/32] setup.c: convert check_repository_format_gently to use strbuf Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 18/32] setup.c: detect $GIT_COMMON_DIR check_repository_format_gently() Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 19/32] setup.c: support multi-checkout repo setup Nguyễn Thái Ngọc Duy
2014-10-01 16:19 ` Johannes Sixt
2014-09-28 1:22 ` [PATCH v3 20/32] wrapper.c: wrapper to open a file, fprintf then close Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 21/32] use new wrapper write_file() for simple file writing Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 22/32] checkout: support checking out into a new working directory Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 23/32] prune: strategies for linked checkouts Nguyễn Thái Ngọc Duy
2014-10-01 16:20 ` Johannes Sixt
2014-09-28 1:22 ` [PATCH v3 24/32] checkout: reject if the branch is already checked out elsewhere Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 25/32] checkout: clean up half-prepared directories in --to mode Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 26/32] gc: style change -- no SP before closing parenthesis Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 27/32] gc: factor out gc.pruneexpire parsing code Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 28/32] gc: support prune --worktrees Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 29/32] count-objects: report unused files in $GIT_DIR/worktrees/ Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 30/32] git_path(): keep "info/sparse-checkout" per work-tree Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 31/32] checkout: don't require a work tree when checking out into a new one Nguyễn Thái Ngọc Duy
2014-09-28 1:22 ` [PATCH v3 32/32] t2025: add a test to make sure grafts is working from a linked checkout Nguyễn Thái Ngọc Duy
2014-09-28 6:35 ` [PATCH v3 00/32] nd/multiple-work-trees Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqfvga2ai9.fsf@gitster.dls.corp.google.com \
--to=gitster@pobox$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=marcnarc@xiplink$(echo .)com \
--cc=pclouds@gmail$(echo .)com \
--cc=philipoakley@iee$(echo .)org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox