git clone tag shallow

git clone tag shallow

[Thibault Kruse]

Hi all,

I notice that using git 1.8.3, I can call
git clone repo1 repo2 --branch tagname
with a tag, not a branch. Is this going to be a stable and documented feature?

cheers,
  Thibault

Re: git clone tag shallow

[Duy Nguyen]

On Mon, Feb 18, 2013 at 2:13 AM, Thibault Kruse
<tibokruse@googlemail.com> wrote:
> Hi all,
>
> I notice that using git 1.8.3, I can call
> git clone repo1 repo2 --branch tagname
> with a tag, not a branch. Is this going to be a stable and documented feature?

There is a test for --branch=tag in t5601, so I say it's supported. If
the document is not clear, patches are welcome.
-- 
Duy

Re: git clone tag shallow

[Thibault Kruse]

Hi Duy,

Looking closer at the rest of the docs, I guess it is consistent, but
not terribly helpful.
Throughout the docs (--help and man), it is never very clear what
objects a command
may accept or not. here is what I get from it:

Whenever a command description involves "<branch>" this can, depending
on the command, refer to
1) a name that, when prepended with "refs/heads/", is a valid ref,
2) a name that, when prepended with "refs/heads/" or "refs/tags", is a
valid ref,
3) a name that, when prepended with "refs/[heads|tags]/", or unique in
"refs/remotes/*/" is a valid ref

Now in the docu I don't see a nice distinction between 1), 2) and 3).
I could work on a patch if someone
tells me how to clearly distinguish those cases.

Example for 1)
git clone --branch <branch>    in git 1.7.x
Example for 2)
git clone --branch <branch>    in git 1.8.x
Example for 3)
git checkout <branch>    in git 1.8.x

I would like the docs to relate to those e.g. as
1) git clone --branch <local-branch>
2) git clone --branch <local-branch-or-tag>
3) git checkout <commit-label>
or something similar, in the future. But I wont create a patch before
having some blessing on the labels to use.


On a related note, what would help my use-case would be an extension
to git clone such
that git clone [--deep] accepted also most other kinds of commit
references, such as SHA-IDs.

Such that
git clone --deep --branch 2h134vjvbc
would work. Is there a plan to introduce that as well?

cheers,
  Thibault


On Mon, Feb 18, 2013 at 7:49 AM, Duy Nguyen <pclouds@gmail.com> wrote:
> On Mon, Feb 18, 2013 at 2:13 AM, Thibault Kruse
> <tibokruse@googlemail.com> wrote:
>> Hi all,
>>
>> I notice that using git 1.8.3, I can call
>> git clone repo1 repo2 --branch tagname
>> with a tag, not a branch. Is this going to be a stable and documented feature?
>
> There is a test for --branch=tag in t5601, so I say it's supported. If
> the document is not clear, patches are welcome.
> --
> Duy

Re: git clone tag shallow

[Junio C Hamano]

Thibault Kruse <tibokruse@googlemail.com> writes:

> Whenever a command description involves "<branch>" this can, depending
> on the command, refer to
> 1) a name that, when prepended with "refs/heads/", is a valid ref,
> 2) a name that, when prepended with "refs/heads/" or "refs/tags", is a
> valid ref,
> 3) a name that, when prepended with "refs/[heads|tags]/", or unique in
> "refs/remotes/*/" is a valid ref
>
> Now in the docu I don't see a nice distinction between 1), 2) and 3).
> I could work on a patch if someone
> tells me how to clearly distinguish those cases.

It is _very_ true that we do not give strict distinction in many
cases in the SYNOPSIS section.

It is clear that (1) should use <branch> or even <branch-name>.
"git checkout master" and "git checkout head/master" mean very
different things.  The former is the "git checkout <branch-name>"
case---checkout the named branch and prepare to grow the history of
that branch.  The latter is "git checkout <committish>"---detach the
HEAD at that commit, and even when the committish was named using
the name of an existing branch (e.g. "master^0" or "heads/master"),
prevent future commits made in that state from affecting the branch.

I am not sure why you meant to treat (2) and (3) differently,
though.  Care to elaborate?

And there is (4) that is not in your list.

A name that is not a local branch name (i.e. no refs/heads/$name)
and that there is only one ref that matches refs/remotes/*/$name,
such a name is special-cased in "git checkout $name".  But I do not
know it is worth giving a name to such a narrow concept that is only
used for a single hacky special case.  Whatever word you invent and
call such a name (perhaps "remote branch name"?), you would need to
repeat the first three lines of this paragraph in the description to
define that word anyway.

Outside "git checkout", we historically deliberately stayed loose in
an attempt to help beginners by avoiding <committish> or <ref>, when
most people are expected to feed branch names to the command and
used <branch>.  I am not sure if it is a good idea to break such a
white lie just to be technically more correct in the first place.
It needs to be done with care to avoid making the resulting text
harder to approach for beginners.

Re: git clone tag shallow

[Thibault Kruse]

Hi Junio,

On Mon, Feb 18, 2013 at 10:22 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Thibault Kruse <tibokruse@googlemail.com> writes:
>
>> Whenever a command description involves "<branch>" this can, depending
>> on the command, refer to
>> 1) a name that, when prepended with "refs/heads/", is a valid ref,
>> 2) a name that, when prepended with "refs/heads/" or "refs/tags", is a
>> valid ref,
>> 3) a name that, when prepended with "refs/[heads|tags]/", or unique in
>> "refs/remotes/*/" is a valid ref
>>
>> Now in the docu I don't see a nice distinction between 1), 2) and 3).
>> I could work on a patch if someone
>> tells me how to clearly distinguish those cases.
>
> It is _very_ true that we do not give strict distinction in many
> cases in the SYNOPSIS section.
>
> It is clear that (1) should use <branch> or even <branch-name>.
> "git checkout master" and "git checkout head/master" mean very
> different things.  The former is the "git checkout <branch-name>"
> case---checkout the named branch and prepare to grow the history of
> that branch.  The latter is "git checkout <committish>"---detach the
> HEAD at that commit, and even when the committish was named using
> the name of an existing branch (e.g. "master^0" or "heads/master"),
> prevent future commits made in that state from affecting the branch.
>
> I am not sure why you meant to treat (2) and (3) differently,
> though.  Care to elaborate?

As in my example, git clone --branch <branch> does not accept all of (3).

I now see that indeed the options section for git clone --branch has
been changed to inlude the information that tags are also allowed, so that's
in order.

> Outside "git checkout", we historically deliberately stayed loose in
> an attempt to help beginners by avoiding <committish> or <ref>, when
> most people are expected to feed branch names to the command and
> used <branch>.  I am not sure if it is a good idea to break such a
> white lie just to be technically more correct in the first place.

That's fair enough, I guess, I am not sure either. If I understand you
right, the Synopsis and
description are supposed to explain the non-hackish usage of commands,
whereas documentation after the OPTIONS headline is supposed to be
more of a complete description. Hence e.g. the synopsis of git-checkout
does not mention the --t,--track,--no-track options, and takes a liberal
approach to option syntaxes (listing '[-p|--patch]', but only '-m',
but not '[-m|--merge]'),
similar git-clone help does not mention the '--branch' option in the synopsis
for that reason, I guess. Do I get this right?

Does this also extend to the (bash) tab completion?
E.g. hitting tab after "git clone --", offers me (Ubuntu precise, git 1.7.9.5):
--bare           --local          --no-checkout    --origin
--reference      --template=
--depth          --mirror         --no-hardlinks   --quiet
--shared         --upload-pack

missing:
---recursive --recurse-submodules (--[no-]single-branch)
--separate-git-dir --verbose --progress --branch

Is this also intentional?

cheers,
  Thibault

Re: git clone tag shallow

[Junio C Hamano]

Thibault Kruse <tibokruse@googlemail.com> writes:

>> I am not sure why you meant to treat (2) and (3) differently,
>> though.  Care to elaborate?
>
> As in my example, git clone --branch <branch> does not accept all of (3).

That is a prime example of outside "checkout" we give a white lie to
show the most common <branch> to help beginners, I think.

> That's fair enough, I guess, I am not sure either. If I understand you
> right, the Synopsis and
> description are supposed to explain the non-hackish usage of commands,
> whereas documentation after the OPTIONS headline is supposed to be
> more of a complete description.

It would go more like

	SYNOPSIS
        	git foo <branch>
	DESCRIPTION
        	"git foo" distims doshes in <branch>.
	ARGUMENTS
		* <branch>: the branch to distim doshes in.
		  While it is most common to name a branch, you
                  can give any <committ-ish> to it.

if and only if use is <branch> is the most common and using
arbitrary commit is a rare case.  In other cases, we would be better
to say <committish> on the SYNOPSIS part.  That commonness/rareness
is a case-by-case matter, I would think.