git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Jakub Narebski <jnareb@gmail.com>
Date
Sep 14, 2008, 21:12 UTC
Message-ID
<m3iqsymnyd.fsf@localhost.localdomain>
In-Reply-To
<1221397685-27715-16-git-send-email-pclouds@gmail.com>
I will comment only on the documentation...
Nguyễn Thái Ngọc Duy <pclouds@gmail.com> writes:
Show 5 quoted lines
> 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
[...]
Show 15 quoted lines
> +--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.

Show 8 quoted lines
> +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/?
Show 6 quoted lines
> +
> +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.

Show 9 quoted lines
> +
> +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)?

Show 5 quoted lines
> +
> +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.
Show 8 quoted lines
> +
> +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
Previous: Junio C HamanoNext: Baz
Message 22 of 35 in “Narrow/Partial/Sparse checkout”
  1. 00/16 Narrow/Partial/Sparse checkoutNguyễn Thái Ngọc Duy, Sep 14, 2008
  2. 01/16 Extend index to save more flagsNguyễn Thái Ngọc Duy, Sep 14, 2008
  3. 02/16 Introduce CE_NO_CHECKOUT bitNguyễn Thái Ngọc Duy, Sep 14, 2008
  4. 03/16 update-index: refactor mark_valid() in preparation for new optionsNguyễn Thái Ngọc Duy, Sep 14, 2008
  5. 04/16 update-index: add --checkout/--no-checkout to update CE_NO_CHECKOUT bitNguyễn Thái Ngọc Duy, Sep 14, 2008
  6. 05/16 ls-files: add --narrow-checkout option to "will checkout" entriesNguyễn Thái Ngọc Duy, Sep 14, 2008
  7. 06/16 Add tests for updating no-checkout entries in indexNguyễn Thái Ngọc Duy, Sep 14, 2008
  8. 07/16 Prevent diff machinery from examining worktree outside narrow checkoutNguyễn Thái Ngọc Duy, Sep 14, 2008
  9. 08/16 checkout_entry(): CE_NO_CHECKOUT on checked out entries.Nguyễn Thái Ngọc Duy, Sep 14, 2008
  10. 09/16 ls-files: apply --deleted on narrow area onlyNguyễn Thái Ngọc Duy, Sep 14, 2008
  11. 10/16 grep: skip files that have not been checked outNguyễn Thái Ngọc Duy, Sep 14, 2008
  12. 11/16 unpack_trees(): add support for narrow checkoutNguyễn Thái Ngọc Duy, Sep 14, 2008
  13. 12/16 narrow spec: put '+' before a spec will change semantic of '*'Nguyễn Thái Ngọc Duy, Sep 14, 2008
  14. 13/16 ls-files: add --narrow-match=spec option for testing narrow matchingNguyễn Thái Ngọc Duy, Sep 14, 2008
  15. 14/16 clone: support narrow checkout with --path optionNguyễn Thái Ngọc Duy, Sep 14, 2008
  16. 15/16 checkout: add new options to support narrow checkoutNguyễn Thái Ngọc Duy, Sep 14, 2008
  17. 16/16 ls-files: add --overlay optionNguyễn Thái Ngọc Duy, Sep 14, 2008
  18. Jakub NarebskiSep 14, 2008
  19. Junio C HamanoSep 15, 2008
  20. Nguyen Thai Ngoc DuySep 16, 2008
  21. Junio C HamanoSep 16, 2008
  22. Jakub NarebskiSep 14, 2008
  23. BazSep 16, 2008
  24. Johannes SixtSep 16, 2008
  25. Nguyen Thai Ngoc DuySep 16, 2008
  26. Jakub NarebskiSep 14, 2008
  27. Junio C HamanoSep 15, 2008
  28. Jakub NarebskiSep 14, 2008
  29. Junio C HamanoSep 15, 2008
  30. Nguyen Thai Ngoc DuySep 16, 2008
  31. Jakub NarebskiSep 14, 2008
  32. Junio C HamanoSep 15, 2008
  33. Jakub NarebskiSep 14, 2008
  34. Junio C HamanoSep 15, 2008
  35. Jakub NarebskiSep 14, 2008

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.