pushing from a shallow repo allowed?

pushing from a shallow repo allowed?

[Joey Hess]

[-- Attachment #1: Type: text/plain, Size: 1071 bytes --]

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

-- 
see shy jo

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: pushing from a shallow repo allowed?

[Mikael Magnusson]

2009/2/12 Joey Hess <joey@kitenet.net>:
> 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?

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

> 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

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.

-- 
Mikael Magnusson

[PATCH] git-clone.txt: document that pushing from a shallow clone may work

[Adeodato Simó]

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:

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

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(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 95f08b9..1b4f864 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -133,8 +133,10 @@ then the cloned repository will become corrupt.
 --depth <depth>::
 	Create a 'shallow' clone with a history truncated to the
 	specified number of revisions.  A shallow repository has a
-	number of limitations (you cannot clone or fetch from
-	it, nor push from nor into it), but is adequate if you
+	number of limitations: you cannot clone or fetch from it,
+	nor push into it; pushing from it into a regular repository
+	may work correctly in some cases, but it is not guaranteed to
+	always work.  However, a shallow repository is adequate if you
 	are only interested in the recent history of a large project
 	with a long history, and would want to send in fixes
 	as patches.
-- 
1.6.2.rc2.271.ge939

Re: [PATCH] git-clone.txt: document that pushing from a shallow clone may work

[Johannes Sixt]

Adeodato Simó schrieb:
> @@ -133,8 +133,10 @@ then the cloned repository will become corrupt.
>  --depth <depth>::
>  	Create a 'shallow' clone with a history truncated to the
>  	specified number of revisions.  A shallow repository has a
> -	number of limitations (you cannot clone or fetch from
> -	it, nor push from nor into it), but is adequate if you
> +	number of limitations: you cannot clone or fetch from it,
> +	nor push into it; pushing from it into a regular repository
> +	may work correctly in some cases, but it is not guaranteed to
> +	always work.  However, a shallow repository is adequate if you

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

Re: [PATCH] git-clone.txt: document that pushing from a shallow clone may work

[Adeodato Simó]

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

> Adeodato Simó schrieb:
> > @@ -133,8 +133,10 @@ then the cloned repository will become corrupt.
> >  --depth <depth>::
> >  	Create a 'shallow' clone with a history truncated to the
> >  	specified number of revisions.  A shallow repository has a
> > -	number of limitations (you cannot clone or fetch from
> > -	it, nor push from nor into it), but is adequate if you
> > +	number of limitations: you cannot clone or fetch from it,
> > +	nor push into it; pushing from it into a regular repository
> > +	may work correctly in some cases, but it is not guaranteed to
> > +	always work.  However, a shallow repository is adequate if you

> 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.

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,

-- 
Adeodato Simó                                     dato at net.com.org.es
Debian Developer                                  adeodato at debian.org
 
«Ara que ets la meva dona, te la fotré fins a la melsa, bacona!»
                -- Terenci Moix, “Chulas y famosas”

Re: [PATCH] git-clone.txt: document that pushing from a shallow clone may work

[Jay Soffian]

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

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

j.

Re: [PATCH] git-clone.txt: document that pushing from a shallow clone may work

[Adeodato Simó]

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

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

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

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 at net.com.org.es
Debian Developer                                  adeodato at debian.org
 
- Oh my God, you're pimping me out for a new roof?
- And windows!
                -- Andrew and Bree Van De Kamp

Re: [PATCH] git-clone.txt: document that pushing from a shallow clone may work

[Junio C Hamano]

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

>> Wy not just say "pushing into a shallow repository is not supported"
>> instead of "pushing into a shallow repository won't work."
>
> 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.

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.

Re: [PATCH] git-clone.txt: document that pushing from a shallow clone may work

[Johannes Schindelin]

Hi,

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

> 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.

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

Re: [PATCH] git-clone.txt: document that pushing from a shallow clone may work

[Adeodato Simó]

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

> 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.

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,

-- 
Adeodato Simó                                     dato at net.com.org.es
Debian Developer                                  adeodato at debian.org
 
Man is certainly stark mad; he cannot make a flea, yet he makes gods by the
dozens.
                -- Michel de Montaigne

Re: [PATCH] git-clone.txt: document that pushing from a shallow clone may work

[Junio C Hamano]

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

> On Wed, 4 Mar 2009, Junio C Hamano wrote:
>
>> 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.
>
> Exactly.

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.