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

From: Jakub Narebski <[email-masked]>
Date: Sun, 14 Sep 2008 14:12:28 -0700 (PDT)

I will comment only on the documentation...

Nguyễn Thái Ngọc Duy <[email-masked]> writes:

> These options include:
> 
>  --full: return to full checkout (default)
>  --path: narrow checkout to some areas according to given spec
>  --add-path/--remove-path: adjust current narrow checkout

Hmmm... I'm not sure if such formatting of commit message, with
body being not independent on the subject (first line of commit
message) is a good idea.

> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
[...]
> +--full::
> +	Quit narrow checkout mode. Return to full checkout.
> +
> +--path=<narrow_spec>::
> +	Re-apply new narrow spec on current working directory to
> +	form new checkout area.
> +
> +--add-path=<narrow_spec>::
> +	Checkout more areas specified by narrow spec to current
> +	checkout area.
> +
> +--remove-path=<narrow_spec>::
> +	Narrow checkout area by removing files specified by narrow spec
> +	from current checkout area. This operation will fail if there
> +	is unmerged or modified files in the removing areas.

Subversion from version 1.5 supports something called "Sparse directories",
http://blogs.open.collab.net/svn/2007/06/sparse-director.html (as pointed
out by Bjorn Steinbrink (doener_) on #git).  Subversion has the following
options for 'svn checkout':

  -N::
  --non-recursive::
         Checkout only the main directory of the trunk and not the
         sub-directories
   --depth=empty::
         Updates will not pull in any files or subdirectories not
         already present.
   --depth=files::
         Updates will pull in any files not already present,
         but not subdirectories.
   --depth=immediates::  
         Updates will pull in any files or subdirectories not
         already present; the subdirectories will have depth=empty.
   --depth=infinity::
         Updates will pull in any files or subdirectories not
         already present; the subdirectories will have depth=infinity.
         Equivalent to today's default update behavior.

I'm not sure if those ways of limiting are worth implementing, but
I guess that they are at least worth thinking about.

> +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 required. Narrow
> +checkout is a mode that limits checkout area according to your
> +rules.

Perhaps s/required/needed/?

> +
> +Because narrow checkout uses new index format, it will be
> +incompatible with git prior to 1.6.0. In order to make your
> +working directory work with those versions, you can use `git
> +checkout --full` to return to normal mode (and compatible index
> +format).

Very nice to have those compatibility concerns mentioned upfront.
In short: new feature, wouldn't work with git prior to 1.6.0.

I hope that nobody mistakes _working_ with repository with 
partial / sparse / narrow checkout, which requires >= 1.6.0,
with being able to clone / fetch such repository, where there
are no limitations, contrary for example to what was for submodule
support.

> +
> +Narrow works by applying your rules to the index, marking which
> +file you need and which file you need not. Modified/Unmerged
> +files cannot be marked unneeded. Unnecessary files will be
> +removed from working directory.  Note that after this step,
> +removed files can still be added to working directory when they
> +are needed by any git command. For example, when you have a merge
> +conflict, conflicted files will be checked out on working
> +directory and will no longer be marked "unneeded".

This paragraph I think need some more love...

So the "checkout rules" are meant to mark which paths are "wanted"
or "needed", and we would like to have in the checkout, and which
files are "unwanted" or "not needed" ("unneeded"?) and we want to
not have them present in working directory; something akin to accept
and deny rules, isn't it?

What are the rules, does all files except those marked explicitely
as needed are unneeded, or do you have to first mark all files as
unneeded?

How would the following table look like:

  working directory  || needed       | not needed    |
  ----------------------------------------------------
  file is absent     || checkout     | no change     |
  file is present    || no change    | removed       |
  file is modified   || conflict     | conflict?     |

> +
> +New files after merges will always be "needed". You can also
> +apply rules when switching branches to avoid unwanted new files.

Does it mean that if merge brings some new files, then those
files would be "needed" (without "no checkout" bit)?

What does it mean this sentence about switching branches:
how does partial/sparse/narrow checkout rules change when
switching to other branch (which, like 'html' and 'todo'
branches in git repository, can be completely unrelated)?

> +
> +Files that are marked "no-checkout" will be treated like entries
> +with "assume-unchanged bit" (see linkgit:git-update-index[1]). In
> +short, Git will never look for those files in working directory
> +no matter whether they exist in working directory.

Perhaps add that they would be marked with "no checkout" bit, and
refer to --no-checkout flag of git-update-index?  I'm not sure here
about that...

> +
> +You can apply your rules at once with --path option, or do it
> +incrementally with --add-path and --remove-path.

Nice.

> +
> +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?

Second, wouldn't it be better to use '**' to match also '/'?
Changing meaning of '*' using per-path flag seems a bit bad.

-- 
Jakub Narebski
Poland
ShadeHawk on #git