Re: checkout extra files

> Junio C Hamano <gitster@pobox.com> writes:
>
>> But that is not what is happening at all.  What goes on is far
>> simpler than that.
>>
>>  - the shell sees '*', matches it against working tree files, to
>>    obtain "f1" and "f2";
>>
>>  - the shell tells "git" to "checkout e6f935e -- f1 f2";
>>
>>  - "git" looks into the tree of e6f935e to find paths that match
>>    "f1" and "f2".
>>
>> When "git" is run by the shell in the last step, it has _no_ clue
>> that the end user typed "*" from the shell.  It only sees "f1" and
>> "f2" on the command line.  There is no "set T" to be intersected
>> with "set W", so stop thinking in those terms, and you will be fine.
>>
>> Now the question is, _you_ will be fine, but can the documentation
>> be updated in such a way so that it will help _others_ to also stop
>> thinking about "intersection between set W and set T"?  I do not
>> have a good answer to that.
>
> Let's do this.  I do not want a shell tutorial in "git checkout"
> documentation, but this would fit better in the documentation for
> the CLI convention.

>
> -- >8 --
> gitcli: contrast wildcard given to shell and to git
>
> People who are not used to working with shell may intellectually
> understand how the command line argument is massaged by the shell
> but still have a hard time visualizing the difference between
> letting the shell expand fileglobs and having Git see the fileglob
> to use as a pathspec.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> Documentation/gitcli.txt | 16 ++++++++++++++++
> 1 file changed, 16 insertions(+)
>
> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt
> index ea17f7a..220621b 100644
> --- c/Documentation/gitcli.txt
> +++ w/Documentation/gitcli.txt
> @@ -38,6 +38,22 @@ arguments.  Here are the rules:
>    you have to say either `git diff HEAD --` or `git diff -- HEAD` to
>    disambiguate.
>
> + * Many commands allow wildcards in paths, but you need to protect
> +them from getting globbed by the shell.  These two mean different 
> things:
> ++
> +--------------------------------
> +$ git checkout -- *.c
> +$ git checkout -- \*.c
> +--------------------------------
> ++
> +The former lets your shell expand the fileglob, and you are asking
> +the dot-C files in your working tree to be overwritten with the 
> version
> +in the index.  The latter passes the `*.c` to Git, and you are asking
> +the paths in the index that match the pattern to be checked out to 
> your
> +working tree.  After running `git add hello.c; rm hello.c`, you will 
> _not_
> +see `hello.c` in your working tree with the former, but with the 
> latter
> +you will.
> +
> When writing a script that is expected to handle random user-input, it 
> is
> a good practice to make it explicit which arguments are which by 
> placing
> disambiguating `--` at appropriate places.