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.
