Re: [PATCH 15/16] checkout: add new options to support narrow checkout

[Jakub Narebski <jnareb@gmail.com>]

On Mon, 15 Sep 2008 16:01, Nguyen Thai Ngoc Duy wrote:
> On 9/15/08, Jakub Narebski <jnareb@gmail.com> wrote:
>> [I don't see mails I am replying to on GMane interface to git mailing
>>   list, so threads might be broken. Strange... Perhaps too long lines
>>   were cause of rejection by anti-SPAM vger filter?]
> 
> It was because I used zenbe.com (limited choices at work) to send
> mails and did not realize until too late that zenbe.com did not encode
> UTF-8 properly in mail headers. It made vger.k.o nervous and refuse to
> accept my mails.

Yes, vger anti-SPAM filter is quite "trigger happy"...

>>  On Mon, 15 Sep 2008, Duy Nguyen wrote:
>>> On 09/15/2008 "Jakub Narebski" <jnareb@gmail.com> wrote:

>>>>> +Narrow spec will be used to specify how you want to narrow your
>>>>> +checkout. It is a list of pathspecs separated by colons. Each
>>>>> +patchspec specifies what files should be checked out on working
>>>>> +directory. Pathspec can contain wildcards and is relative to
>>>>> +current working directory. Usually asterisk (*) does not match
>>>>> +slashes. If a pathspec is prefixed by a plus sign (+), then
>>>>> +any asterisk will match anything, even slashes.
>>>>
>>>> First, does this mean that you can specify paths containing colons
>>>> (':') only using --add-path and --remove-path, or does it mean that
>>>> you cannot specify paths containg colon ':' (which should be rare)
>>>> at all as checkout limiter / checkout narrowing rule?
>>>
>>> You cannot do othat explicitly unfortunately. You can work-around using
>>> wildcard though.
>>
>> Couldn't you simply escape ':', i.e. write for example Git\:\:Tag.3pm,
>> or Eichten_PRD21\:313,1980_erratum.tex, or \:0.log, or perhaps
>> kmail/jnareb@gmail.com\:@pop.gmail.com\:995, or even something like
>> Mail/inbox/cur/1194202360.32296.mprnq\:2,S, in the same way like you
>> can escape other special characters, for example wildcard characters
>> like '\*' for '*' and '\?' for '?', and of course '\\' for '\'?
> 
> Sure. Somehow I forgot that.

Well, if it is possible, it should be stated in documentation.
Even if it is obvious.


> [...] how about this? Note that document changes that also require code
> change like narrow spec escape or '**' do not get in. I will change it
> when I update code.

> --<--
> Narrow checkout
> ---------------
> 
> Normally when you do checkout a branch, your working directory
> will be fully populated. In some situations, you just need to
> work on certain files, no full checkout is needed. Narrow
> checkout is a mode that limits checkout area according to your
> needs.

You have decided then on the term 'narrow checkout', and not
'partial checkout' or 'sparse checkout', then?
 
It would be nice if git mailing list came with examples of usage for
this feature.  It was quite frequently requested.  I can think off-hand
about two reasons one might want to use 'narrow checkout':

 1.) when you are not interested in files outside some selected
     set, and you don't want to mess files outside this set, even
     by accident.  For example for end-user documentation writers
     it would be Documentation/* (non-recursive).

 2.) when you work on some large monolithic repository which doesn't
     use submodules, and you have limited and small quota (or disk size).
     Usually repository size is smaller or comparable to checkout size,
     and even if it isn't you can use alternates to reduce size of
     repository (assuming that reference repository is hosted outside
     user quota).


> Because narrow checkout uses new index format, it will be
> incompatible with git prior to 1.6.0 regarding worktree operations.
> Repository-only operations such as clone, push, pull... should not be

s/pull/fetch/. pull affects working repository, and it can affect
narrow checkout unexpectedly by conflicts during merge part of pull.

> affected by narrow checkout. In order to make your working directory
> work again with those versions, you can use `git checkout --full` to
> return to normal mode (and compatible index format).

By the way, you have made "git checkout <file>" get file and mark
it "wanted", i.e. clear/zero "no-checkout" bit.  Wouldn't then
"git checkout ." be shorter equivalent to "git checkout --full"?
I'm not saying that '--full' option should be abandoned...

>
> In narrow checkout mode, checkout status of every files in your
> working directory will be recorded in index. If a file is marked
> "no-checkout", it means that file is not needed to be present in
> working directory by user or any git command. When a new file is added
> to index, it will be marked "checkout" unless narrow spec is applied.
> Unmerged files are always "checkout". linkgit:git-update-index[1] can
> be used to update "checkout/no-checkout" status in index. When you
> checkout new files using "git checkout <file>" they will be
> automatically marked "checkout". Other commands such as "git apply"
> can also checkout new files if they are needed.
> 
> "No-checkout" status is very similar to "assume-unchanged bit"
> (see linkgit:git-update-index[1]). The main difference between them
> is "assume unchanged" bit just ignores corresponding files in working
> directory while narrow checkout goes a bit farther, remove those files
> when it is safe to do so.

Good description (although probably could be improved even further).

>
> Narrow spec
> -----------
> 
> Narrow spec is used to easily specify how do you want to form your
> checkout area.  It is a list of pathspecs separated by colons. Each
> patchspec specifies what files should or should not be checked out on
> working directory. Pathspec can contain wildcards and is relative to
> current working directory. Usually asterisk (*) does not match
> slashes. If a pathspec is prefixed by a plus sign (+), then any
> asterisk will match anything, even slashes.

Here I think you should give some examples, perhaps together with
wildcard escaping, escape (backslash) escaping and colon escaping.

> 
> When you apply new narrow spec to your working directory using either
> --path, --add-path or --remove-path, it will update "checkout" status
> in index accordingly. Moreover, if a file is marked "no-checkout" and
> is present in working directory, it will be removed. If a file is
> turned from "no-checkout" to "checkout", then it will be added again
> to working directory. Modified and unmerged entries can't bear
> "no-checkout" status, if narrow spec applies to them, "git checkout"
> will refuse to update working directory.

Do I understand correctly, that if one uses --path=<colon separated list>
_only_ filenames matching one of patterns specified would be checked out,
--add-path=<path> would additionally checkout given path and mark "wanted",
and  --remove-path=<path> would additionally mark "no-checkout" and remove
path?  

What --add-path starts from, i.e. does

  $ git checkout --add-path=.gitignore

starts from empty set if --add-path is first, or from full set as without
--add-path?

And is <pathspec> matched against full pathname, or like .gitignore
rules, i.e. as full pathname if it has at least one '/' in it?

> 
> Narrow spec is not saved by "git checkout". You can form your checkout
> area on one go with --path option, or do it incrementally
> with --add-path and --remove-path.
> --<--

I would probably say that specification used to select which paths to
check out is not saved anywhere, and used only to mark paths in index
as "no-checkout" or not.  Or somehing like that.


Thank you very much for your continued work on this feature!
-- 
Jakub Narebski
Poland