Re: [PATCH] Move worktree setup out of setup_git_directory*

[Junio C Hamano <gitster@pobox.com>]

Nguyễn Thái Ngọc Duy <pclouds@gmail.com> writes:

> setup_git_directory* now work as if there is no worktree.  It may set
> some worktree-related variables but its prefix (and current directory)
> should not be affected by worktree settings.
> ...
> setup_work_tree() will now take the role of recalculating prefix when
> worktree is required.

This definitely needs documented in-tree, Documentation/technical/.

I think we have a good understanding from the end-user point-of-view
how these things work:

 - If you have GIT_DIR exported, then no discovery is attempted.
   We use the GIT_DIR you set it, and the repository lives
   there.  $GIT_DIR/config is the repository config.

 - Otherwise we do the usual discovery going up to find the
   repository.

 - If you have GIT_WORK_TREE exported, or otherwise if the
   config has core.worktree, that's where your worktree is.
   Otherwise, if you have GIT_DIR exported, you do not have a
   worktree.  Else one level above your $GIT_DIR is the toplevel
   of your worktree.

We would need a set of rules for application writers, written
like this (here is just an example of _how_ the rules might be
written, I do not think the contents are correct):

 - At startup:

   - If the command always need to run from a repository, call
     setup_git_directory(), which would complain and die if you
     are outside.

   - If the command can optionally run in a repository, use
     setup_git_directory_gently(&nongit_ok); it won't complain
     but sets nongit_ok to true if run outside a repository.

   In either case, they return prefix string to be used for
   setup_work_tree() later.

   In either case, there is no chdir() done at this point.

 - After calling setup_git_directory(), or you made sure you are
   in a repository after callilng setup_git_directory_gently(),
   call setup_work_tree().  This will chdir to the top of the
   work tree.

 - When you need to know where $GIT_DIR is, call get_git_dir().
   When you need to know where the work tree is, call
   get_git_work_tree().  However, it is an error to call these
   functions before calling setup_git_directory and
   setup_work_tree.