pushing from a shallow repo allowed?

git-clone(1):
	A shallow repository has a number of
        limitations (you cannot clone or fetch from it, nor push from nor
        into it)

This and other documentation (shallow.txt, RelNotes-1.5.0.txt) says you can't push from a shallow repo. But in a simple test of making a commit to a shallow repo and pushing it out, it seems to work. AFAICS, git only guards against pushes *into* a shallow repo, and fetching/cloning from a shallow repository.

Are the docs out of date, or is there really still some problem with pushing from a shallow repo?

BTW, --depth seems to be ignored when making a local clone. This seems to have been fixed in the old shell git-clone in d4110a9726c7cd5cda35b7dd03dc8f85fe3dff0c, was it accidentially lost in the C version?

joey@gnu:~/src/other> git clone --depth 2 git git.shallow Initialized empty Git repository in /home/joey/src/other/git.shallow/.git/ joey@gnu:~/src/other> cd git.shallow joey@gnu:~/src/other/git.shallow> git-log --pretty=oneline|wc -l 17009

git version 1.5.6.5

2009/2/12 Joey Hess <joey@kitenet.net>:

AFAIK, it will work in simple cases, but isn't guaranteed to work.

You most likely need to use the file:// syntax for this to work, otherwise git will just hardlink/copy the whole objects dir without looking at it.

The documentation used to say that pushing from a shallow clone is not supported; this is true, though it may work in some simple cases. If a user notices this fact, such a mismatch between documentation and reality may leave them assuming the documentation is wrong and that pushing from a shallow clone is supported.

This commit updates the documentation to say that pushing from a shallow clone may work in some cases, but that it's not guaranteed to always do.

Signed-off-by: Adeodato Simó <dato@net.com.org.es>
---
Hello,

this is about http://thread.gmane.org/gmane.comp.version-control.git/110100, which got a single reply from Mikael Magnusson stating:

If that's the case, I think it should be documented, for the reasons explained in the commit message.

Thanks!

 Documentation/git-clone.txt |    6 ++++--
 1 files changed, 4 insertions(+), 2 deletions(-)

Adeodato Simó schrieb:

Consider a reader who wants to decide whether --depth should or can be used in a git clone invocation. Is the new wording helpful? If you don't describe those "some cases" in more detail, then we better keep the current wording.

-- Hannes

* Johannes Sixt [Tue, 03 Mar 2009 12:57:22 +0100]:

Well, I don't know if the set of cases where it'll work can be defined in detail to a point where it is useful. If it is, then sure, let's do it.

My point is that if it will work in some cases, then the documentation should *acknowledge that fact*, because else people will assume the documentation is wrong, and believe it is intended to work, which is not the case.

I think doing that is very important, and I hope I'm explaining myself clearly.

Thanks,

On Tue, Mar 3, 2009 at 7:08 AM, Adeodato Simó <dato@net.com.org.es> wrote:

Wy not just say "pushing into a shallow repository is not supported" instead of "pushing into a shallow repository won't work."

j.

* Jay Soffian [Tue, 03 Mar 2009 14:27:29 -0500]:

I don't think such a wording is enough (adjusted, of course, to be about pushing from, not to, which is the case at hand).

But I'll try to stay silent, and see if Junio has an opinion on the matter.

Thanks,

Adeodato Simó <dato@net.com.org.es> writes:

I would be a terrible judge for things like this; I lost my git virginity long time ago.

If I have to say something on this...

 * I think "is not supported" is a succinct way to give good enough
   information, but it would only work for intelligent people.

 * Not everybody is intelligent; some try it out themselves, see that the
   operation _seems to_ work for their limited number of trials, and would
   conclude it would work most of the time.  And they congratulate their
   own intelligence for saying "most of the time", not "always".  And they
   get upset when they see it does not work, even though they have been
   warned.

 * Hence, I do not think "is not supported" is a statement that is a bit
   too weak.  At least you need to say "it may seem to work, but no
   guarantees", _if_ your objective is to cover the backside of "shallow".

But I do not think that is what we should be aiming for to begin with.

It is not like nobody can precisely answer when "pushing from shallow" works and when it doesn't. It would be true for a hack that was not well designed but merely was meant to be "good enough for most of the time", but I do not think "shallow" is that horrible a hack.

Isn't the rule more or less like:

    If your shallow repository's history does not extend long enough and
    the other repository forked before your truncated history, wyou cannot
    compute the common ancestor and you cannot push out.

Hi,

On Wed, 4 Mar 2009, Junio C Hamano wrote:

Exactly.

Back when I wrote the shallow code, I meant to investigate how to detect that condition, and fail gracefully (i.e. with a meaningful error message).

IMHO that is more needed than documentation changes, as it affects more users ;-)

But in the meantime, I had no use for shallow clones, and kind of hoped that it would become somebody else's itch.

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Actually, come to think of it, it is a lot stronger than "cannot compute the common".

The history may look like this:

          R---R---R
         /
  --R---R---X---X---S---S---S

where S are the commits you have in your shallow repository, and R are the commits that exist in the repository that receives your push. Because your history is shallow, neither repository has 'X' that are the commits that need to exist in order to keep the history of recipient repository complete; the recipient is not shallow to begin with, and we do not want to make it shallow.

If you cloned shallowly some time ago, worked without communicating with the other side while the other side progressed, *AND* if the other side's progress included a rewind & rebuild of the history, you would see a similar topology. The leftmost 'S' in the above picture might have been the tip of the branch when you shallowly cloned with depth 1, and since then the remote end may have discarded topmost three commits and have rebuilt its history that leads to the rightmost 'R'. In such a case pushing to the remote's HEAD will fail.

* Junio C Hamano [Wed, 04 Mar 2009 02:45:54 -0800]:

Ah, this is helpful, thanks for it and for the rest of the message. Would you take a patch to include this in the git-clone manpage, maybe with an alternative wording? Eg.:

  Pushing from a shallow repository is not supported, but works when
  you're pushing to branches with a common ancestor in your available
  history (so pushing to the remote HEAD should always work).

I *think* the sentence in brackets is correct; I put it there because in my experience is a feature a lot of people around me want.(¹)

  (¹) I realize this may seem odd, people with push access wanting to be
  able to push from a shallow repository. In case somebody is interested
  in the details, there's been discussion in the debian-python lists
  about a possible move to Git. There currently exists a Subversion
  repository with a lot of packages; many people with access just work
  on a few of them, but do the typical random fix on others from time to
  time. And some of them were concerned about downloading all history
  for over a hundred of repositories. (Which was another of the
  conflicting points, how it's very easy to download all the packages in
  Subversion.)

Cheers,