Re: builtin command's prefix question

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

"Nguyen Thai Ngoc Duy" <pclouds@gmail.com> writes:

> I have been looking at setup_git_directory_gently() lately. From my
> understanding, setup_git_directory* will return a string called
> "prefix" that is passed to builtin commands. What is the exact meaning
> of this prefix?

Some historical background is in order.  For a long time, we only worked
from the very top of the work tree and nowhere else.  The path you get
from the user on the command line was supposed to be relative to the top
of the work tree, the user was supposed to be at the top of the work
tree, no work from subdirectories.

This was limiting, so "setup" was introduced.  The commands originally
worked only from the top would chdir up to the top of the work tree if
it was run from a subdirectory.  This however needs adjustments to the
paths we get from the user from the command line (or stdin for commands
that take such).  If we claim we work from a subdirectory, we should
interpret path given by the user who is in a subdirectory as relative to
that subdirectory.  The way to do this adjustment is to prefix the
subdirectory path to the path given by the user.

So, if you start a command from Documentation/ subdirectory, like this:

	$ cd Documentation
	$ git ls-files howto

internally, ls-files would:

 * Notice it was run from Documentation/ subdirectory;

 * cd up to the top level;

 * prefix "Documentation/" to the pathspec given by the user
   (i.e. "howto"), to form "Documentation/howto";

 * Act as before, except that it strips "Documentation/" from its usual
   output, to retain the illusion of working from that subdirectory.

And prefix is "Documentation/" (note the trailing slash) in such a
case.  If you run from the top, it is NULL to signal that there is no
need to do any of these tricks.

> ... Correct me if I'm wrong. In early (read: no worktree)
> days, cwd was moved to working root directory and prefix contained
> relative path from working root directory to the original cwd. So it
> had a few implications:

>  1. A non-empty prefix indicates cwd has been moved

Correct (I do not know if we care, though)

>  2. If cwd is moved, it is moved to working root directory

Correct ("we always work from top of the tree internally" matters)

>  3. cwd+prefix should point to the current directory at the time the
> command was issued (let's call it "user cwd")

Correct.

> Things change a bit since the rise of worktree:
>  - If GIT_DIR is set and GIT_WORK_TREE is not, prefix is relative to
> the to-be-set-up worktree, but cwd is not changed, so point 3 is gone.
>  - If GIT_DIR is not set and GiT_WORK_TREE is,
>   - and it is found that user cwd is inside a gitdir (bare repo), cwd
> has been moved and prefix is empty, cwd+prefix no longer point to user
> cwd
>   - for other cases, cwd may not be worktree (the real worktree will
> be setup in setup_work_tree or setup_git_directory)

The intention is:

 * If GIT_DIR is set but not GIT_WORK_TREE (nor core.worktree in
   config), you are either inside project.git/ directory of bare
   repository or at the toplevel of worktree-full directory.  This has
   been the traditional behaviour before GIT_WORK_TREE and we shouldn't
   break the existing setups that assume this behaviour.  So in that
   sense, with this combination:

   - If the repository is bare, the value of the prefix should not
     matter; the command that wants to look at prefix by definition
     wants to run from a subdirectory but there is no notion of
     "the user directory being a subdirectory of the top of the work
     tree" in a bare repository;

   - If the repository is not bare, the user directory _MUST_ be at the
     top of the work tree, as that is what the traditional behaviour is.
     Anything else would break existing setups.

     IOW, if you use GIT_DIR and still want to run from a subdirectory
     of the worktree, you must have either GIT_WORK_TREE or
     core.worktree to tell where the top of the worktree is, and if you
     don't, then you must be at the top.

   So the right thing to do in this case is not going anywhere and using
   prefix=NULL.

 * I would say it is a misconfiguration if GIT_DIR is not set and
   GIT_WORK_TREE is, as the sole purpose of GIT_WORK_TREE is so that you
   can work from a subdirectory when you set GIT_DIR.  I may be missing
   an obvious use case that this is useful, but I do not think of any.
   Dscho may be able to correct me on this, as he fixed up the original
   work tree series that was even messier quite a bit during the last
   round.