Toon Claes <toon@xxxxxxxxx> writes: > Add option `--ref` to git-clone(1). This enables the user to clone and > checkout the given named reference. Define "checkout the reference". A ref that is outside of "refs/heads/" MUST NOT be pointed by HEAD, so giving a tag with this option should result in an initial working tree on a detached HEAD. If it is what the new option does (which is similar to the way how we handle a tag when it was given with --branch), we should be more explicit that the ref is *not* checked out, but a deteached HEAD is created to point at the commit referenced. I think the documentation part of this patch does a much better job at it. > It's pretty similar to --branch and > while --branch takes a branch name or tag name, it doesn't take a fully > qualified reference. This allows the user to clone a reference that > doesn't start with refs/heads or refs/tags. This can be useful when the > server uses custom references. "when the server uses custom references" is a rather weak explanation. The answer to "Doctor, it hurts when I turn my elbow in this unnatural direction" is usually "Well, do not do it then". The answer to "Doctor, I cannot use the --branch option because I use non branches to keep track of some histories" should be the same. Why do you want to turn your elbow in an unnatural angle in the first place? Stepping one level higher. The usual way to compose a log message of this project is to - Give an observation on how the current system work in the present tense (so no need to say "Currently X is Y", just "X is Y"), and discuss what you perceive as a problem in it. - Propose a solution (optional---often, problem description trivially leads to an obvious solution in reader's minds). - Give commands to the codebase to "become like so". in this order. The first paragraph that describes what the commit wants to do is better moved down to the last. Justify why you want to turn your elbow in a way other people do not usually do (or why you want unusual hierarchies on the server side), explain that it hurts (or say --branches is limited to branches and tags), and then finally give a solution. > +`--ref` _<name>_:: > + This detaches HEAD and makes it point to the commit where the _<name>_ > + reference is pointing to. In a non-bare repository, this is the ref that > + will be checked out. > + Can be used in conjunction with `--single-branch` and `--no-tags` to > + clone only the given ref. Cannot be combined with `--branch`. OK, so it is an error to give both --branch and --ref at the same time? If you say "git clone --branch foo --branch bar ...", wouldn't the usual last-one-wins rule apply? Shouldn't this work the same way, meaning "git clone --branch foo --ref refs/some/one ..." would behave just like "git clone --ref refs/some/one ...", without treating the "foo" branch any specially? What if --ref is not pointing at a commit-ish? If I in any repository with non-empty history checked out do this: $ git update-ref refs/some/one HEAD: can you clone from this repository with $ git clone --ref=refs/some/one $URL and what happens at the end? > diff --git a/builtin/clone.c b/builtin/clone.c > index e77339c847..384923703d 100644 > --- a/builtin/clone.c > +++ b/builtin/clone.c > @@ -69,6 +69,7 @@ static char *option_template, *option_depth, *option_since; > static char *option_origin = NULL; > static char *remote_name = NULL; > static char *option_branch = NULL; > +static char *option_ref = NULL; If you want to make "With --branch and --ref, the last one wins", this would not be sufficient. > @@ -141,6 +142,8 @@ static struct option builtin_clone_options[] = { > N_("use <name> instead of 'origin' to track upstream")), > OPT_STRING('b', "branch", &option_branch, N_("branch"), > N_("checkout <branch> instead of the remote's HEAD")), > + OPT_STRING(0, "ref", &option_ref, N_("ref"), > + N_("checkout <ref> (detached) instead of the remote's HEAD")), Ditto. > @@ -531,32 +534,64 @@ static struct ref *wanted_peer_refs(const struct ref *refs, > if (option_single_branch) { > struct ref *remote_head = NULL; > > - if (!option_branch) > + if (!option_branch && !option_ref) > remote_head = guess_remote_head(head, refs, 0); > else { > free_one_ref(head); > local_refs = head = NULL; > tail = &local_refs; > - remote_head = copy_ref(find_remote_branch(refs, option_branch)); > + if (option_branch) > + remote_head = copy_ref(find_remote_branch(refs, option_branch)); > + else > + remote_head = copy_ref(find_ref_by_name(refs, option_ref)); This makes --ref ignored when --branch is given. Intended? > diff --git a/t/t5612-clone-refspec.sh b/t/t5612-clone-refspec.sh > index 72762de977..51452bdd6f 100755 > --- a/t/t5612-clone-refspec.sh > +++ b/t/t5612-clone-refspec.sh > @@ -17,6 +17,7 @@ test_expect_success 'setup' ' > git tag two && > echo three >file && > git commit -a -m three && > + git update-ref refs/some/three HEAD && > git checkout -b side && > echo four >file && > git commit -a -m four && > @@ -236,4 +237,38 @@ test_expect_success '--single-branch with detached' ' > test_must_be_empty actual > ' > > +test_expect_success 'with --ref' ' > + git clone --ref=refs/some/three . dir_ref && > + git -C dir_ref for-each-ref refs > refs && Lose SP between ">" and "refs". > + sed -e "/HEAD$/d" \ > + -e "s|/remotes/origin/|/heads/|" refs >actual && > + git for-each-ref refs >expect && > + test_cmp expect actual > +' > + > +test_expect_success 'with --ref and --no-tags' ' > + git clone --ref=refs/some/three --no-tags . dir_ref_notags && > + git -C dir_ref_notags for-each-ref refs > refs && > + sed -e "/HEAD$/d" \ > + -e "s|/remotes/origin/|/heads/|" refs >actual && > + git for-each-ref refs/heads >expect && > + git for-each-ref refs/some >>expect && > + test_cmp expect actual > +' > + > +test_expect_success '--single-branch with --ref' ' > + git clone --single-branch --ref=refs/some/three . dir_single_ref && > + git -C dir_single_ref for-each-ref refs > actual && > + git for-each-ref refs/some >expect && I would expect refs/some/three and nothing else comes from refs/some hierarchy, as the clone was done with "--ref=refs/some/three". Is there a particular reason why this for-each-ref is looser and take anything under "refs/some/"? > + git for-each-ref refs/tags >>expect && This is because the above is not giving --no-tags, I guess. > + test_cmp expect actual > +' > + > +test_expect_success '--single-branch with --ref and --no-tags' ' > + git clone --single-branch --ref=refs/some/three --no-tags . dir_single_ref_notags && > + git -C dir_single_ref_notags for-each-ref refs > actual && > + git for-each-ref refs/some >expect && Same comment on the looseness of this one. Lack of refs/tags is expected and it is a good thing to test that. > + test_cmp expect actual > +' There may be others, but three cases that are not tested but should be I spotted offhand are: * "clone --ref=refs/some/three --no-ref" acts as if we gave no "--refs" at all. * interaction when "--ref=refs/some/three" and "--branch=main" are given at the same time. * the command gracefully fail when the given ref points at a tree or a blob. Thanks.