Re: [PATCH 1/2] ls-files: adding support for submodules

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

As this is relevant to what to call the prefix thing that is passed
down to an internal re-invocation of ls-files and how to explain it
to end-users...

Junio C Hamano <gitster@pobox.com> writes:

> I agree that this is not specific to submodules; this is closely
> related to what we internally call "prefix", but is different.
>
> In any case, I would strongly recommend against exposing this (or
> anything for that matter) "--prefix" to the end-user,...

I have a slight suspicion that this was what made you say earlier
that I was against exposing this at all to end users, but what I
meant was a plain boring "prefix" is a bad name and nothing more
than that.

> What we internally call "prefix" and "--submodule-prefix" is closely
> related in that they both interact with pathspecs.  "prefix" gets
> prepended to elements of an end-user supplied pathspec before a
> full-path-in-the-repository (i.e. a path in the index and a path
> relative from the top of the working tree) is matched against them.

In a sense, this new thing is a superset of the existing GIT_PREFIX,
which gives the current working directory from the end user's point
of view relative to the actual current working directory.  The "git"
wrapper, when running a "git thing" from a subdirectory of a working
tree, chdir(2)s up to the top-level before spawning the "thing"
subcommand that is not built-in or a third-party "git-thing" binary
on user's $PATH; so "git-thing" binary will be told via $GIT_PREFIX
relative to what directory path-like things the end user supplied to
the command (e.g. "-o outfile" argument and pathspecs) need to be
interpreted.  The new thing can override the $GIT_PREFIX to allow
path-like things to be interpreted relative to somewhere _above_ the
top-level of the working tree.

I am tempted to suggest GIT_SUPER_PREFIX, 50% because I cannot think
of any better word, 40% because I think it actually makes sense (in
the sense that this comes _above_ it, hence "super", and also in the
sense that this is something your "super" project would give you),
and 10% because I hope that being ridiculous would nudge people to
come up with a better alternative ;-)

And from that point of view ...

>  * It is unclear how this should interact with commands that are run
>    in a subdirectory of the working tree.  E.g. what should the
>    prefix and the pathspec look like if the command in the above
>    example is started in w/git.git/Documentation subdirectory, i.e.
>
>     $ cd ~
>     $ git -C w/git.git/Documentation ls-files \
>         --submodule-prefix=??????? -- '???????' |
>       xargs ls -1 -l
>
>    Should we error out if we are not at the top of the working tree
>    when --submodule-prefix is given?

... the answer to this question becomes clear.  It is not possible
to _be_ in a subdirectory "Documentation" of this working tree and
in a directory "~" above this working tree at the same time, so we
simply should forbid running the command from anywhere other than
the top of the working tree (i.e. the internal "prefix" and
GIT_PREFIX must be empty) when the super-prefix is set by erroring
it out.  When we realize that "prefix" adds to the paths that are
supplied by the user (e.g. when the user says Makefile while in t/
subdirectory, i.e. GIT_PREFIX=t/, s/he means t/Makefile), but this
new thing subtracts from the paths given by the user (e.g. when the
user gives a pathspec 'w/git.git/D*' while setting the super thing
as w/git.git, because s/he is at ~/, the pathspec matcher
conceptually subtracts w/git.git/ from the pathspec before matching
them against the paths it finds in the index), it becomes clear that
giving both at the same time is awkward and not very useful.