git-clone --single-branch clones objects outside of branch

Hi,

I'm reporting some git-clone behavior regarding --single-branch that I found unexpected after reading the docs. I'm using git 2.25.0.

The git-clone docs for --single-branch say:

(from: https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---no-single-branch )

However, when I attempted this with a local repo, I found that objects located only in branches other than the branch I specified are also cloned. Also, this is true even if the remote repo has only loose objects (i.e. no pack files). So it doesn't appear to be doing this only to avoid creating new files.

In contrast, git-fetch behaves as expected (including locally). git-fetch appears to fetch only objects in the given branch, when a branch is specified.

Below are some commands to assist with reproducing this situation (but you will need to update the path in the `git-remote add` invocation below). At the least, it seems like the docs should clarify the behavior. (The Python commands were for when I was doing some experiments with pack files.)

mkdir repo1 cd repo1 git init python -c "print('a\n' + 10 * 'x\n')" > a.txt git add a.txt git commit -m "add a" # Get object id to check existence with `git cat-file -t` below. git hash-object a.txt

git checkout -b dev python -c "print('b\n' + 10 * 'x\n')" > b.txt git add b.txt git commit -m "add b" # Get object id to check existence with `git cat-file -t` below. git hash-object b.txt

git checkout master

cd .. mkdir repo2 cd repo2 git init git remote add other file:///<path-to-repo1> git fetch other master

cd .. git clone --branch master --single-branch repo1 repo3

Thanks, --Chris

On Sun, Jan 26, 2020 at 04:39:52AM -0800, Chris Jerdonek wrote:

This is the expected outcome, because in your example you're cloning on the local filesystem. By default that enables some optimizations, one of which is to hard-link the object files into the destination repository. That avoids the cost of copying and re-hashing them (which a normal cross-system clone would do). And it even avoids traversing the objects to find which are necessary, instead just hard-linking everything.

So with:

You should be able to see with "git for-each-ref" in repo3 that you only got the "master" branch, but not "dev". But those extra objects are available to you, because of the hard-links.

If you do:

  git clone --branch master --single-branch --no-local repo1 repo4

then repo4 will not have the objects (we really will send a packfile across a pipe, just as we would across the network for a cross-system clone).

This one behaves as you expected because git-fetch does not perform the same optimizations (it wouldn't make as much sense there, as generally in a fetch we already have most of the objects from the other side anyway, so hard-linking would just give us duplicates).

-Peff

On Sun, Jan 26, 2020 at 9:55 PM Jeff King <peff@peff.net> wrote:

Thanks for the reply. It's okay for that to be the expected behavior. My suggestion would just be that the documentation for --single-branch be updated to clarify that objects unreachable from the specified branch can still be in the cloned repo when run using the --local optimizations. For example, it can matter for security if one is trying to create a clone of a repo that doesn't include data from branches with sensitive info (e.g. in following Git's advice to create a separate repo if security of private data is desired: https://git-scm.com/docs/gitnamespaces#_security ).

I'm guessing other flags also don't apply when --local is being used. For example, I'm guessing --reference is also ignored when using --local, but I haven't checked yet to confirm. It would be nice if the documentation gave a heads up in cases like these. Even if hard links are being used, it's not clear from the docs whether the objects are filtered first, prior to hard linking, when flags like --single-branch and --reference are passed.

Incidentally, here's a thread from 2010 requesting that this optimization be available in the git-fetch case: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=573909 (I don't know how reports on that Debian list relate to this list.)

--Chris

On Sun, Jan 26, 2020 at 10:46:07PM -0800, Chris Jerdonek wrote:

I think it would make sense to talk about that under "--local". There are other subtle reasons you might want "--no-local", too: it will perform more consistency checks, which could be valuable if you're thinking about deleting the old copy.

I'm not sure how much Git guarantees in general that you won't get extra objects. It's true that we try to avoid sending objects that aren't needed, but it's mostly as an optimization. If we later modified pack-objects to sometimes send unneeded objects (say, because we're able to compute the set more efficiently if we use an approximation that errs on the conservative side), then I think that's something we'd consider. And I suppose it's already possible with the dumb-http protocol, which has to fetch whole packfiles. And the same would be true of recently proposed schemes to clients to a pre-generated packfile URL.

No, "--reference" behaves as usual. However, "--depth" is ignored (and issues a warning). I don't think it would be wrong to issue a warning when --single-branch is used locally (though it would not be "single branch is ignored, since it does impact which refs are copied). But I kind of wonder if it would be annoying for people who don't care about having the extra objects reachable.

Sometimes they get forwarded here, and sometimes not. :)

I think there are subtle issues that make naively using the optimization a bad idea, as it could actually backfire and cause more disk usage. E.g., consider a sequence like this:

  1. Repo A has a 100MB packfile.

  2. "git clone A B" uses hardlinks. Now we have two copies of the repo,
     storing 100MB.

  3. Repo A adds a few more commits, and then does a "git gc", breaking
     the hardlinks. Now we have ~200MB used. We're no worse off than if
     we hadn't done the hardlinks in the first place.

  4. Repo B fetches from A. It wants the new commits, but they're in
     repo A's big packfile. So it hardlinks that. We have ~200MB in repo
     B, but half of that is hardlinked and shared with A. So we're still
     using ~200MB. So far so good.

  5. Repo A repacks again, breaking the hardlinks. Now it's using
     ~100MB, but repo B is still using ~300MB. We're worse off than we
     would be without the optimization.

If you really want to keep sharing objects over time, I think using "clone -s" is a better choice (though it comes with its own complications and dangers, too; see the git-clone documentation).

-Peff

On Tue, Jan 28, 2020 at 1:48 AM Jeff King <peff@peff.net> wrote:

On this, I found that --reference does behave differently in the way that I suspected. For example, when run with the default --local, I found that git-clone will create hard links in the new repo to loose objects, even if those objects already exist in the reference repository. When run with --non-local, the objects in the reference repository weren't copied (I didn't find them in the cloned repo's pack file).

So in addition to --single-branch, this seems to be another case where `git-clone --local` will ignore the provided options when deciding what files inside .git/objects/ to hard-link. It just hard-links everything. This is another example of something that I think would be worth mentioning in the docs in some form. Currently, the documentation for --reference suggests that objects won't be created in the new repo if they already exist in the reference repository.

--Chris

On Tue, Jan 28, 2020 at 05:59:54PM -0800, Chris Jerdonek wrote:

Sure, but I'd just consider that the same issue: hardlinking takes everything in the object database without regard to what's needed. So --reference still works (and when you repack and break the hardlinks, it will drop any duplicates as usual), but obviously you have access to the extra hardlinked objects in the meantime.

IOW, I don't think it's worth calling this out in the --reference documentation, but could be in the --local documentation. Because the unusual implication is the same whether --reference is used or not.

It says:

  Using an already existing repository as an alternate will require
  fewer objects to be copied from the repository being cloned, reducing
  network and local storage costs.

which I think is still technically true. The hardlinks are free in terms of storage (and there's no network cost by definition). So at worst --reference is doing nothing to start with. And the repository has been setup in such a way that it may yield benefits later (after you repack and the hardlinks are broken).

This is maybe splitting hairs a bit. The thing that matters, I think, is where a documentation change should go (and what it should say).

-Peff