git pull --rebase原始标记名？

Question

I'm digging through some production scripts that use git, and trying to make sense of this command:

git pull --rebase origin "${tag_or_commit}"

From what I'm finding in the documentation for git pull and git rebase , it looks like the only thing that should ever be in that tag_or_commit bash variable, would have to be a branch name for the command to work at all.

Is there documented behavior for what this command will do given a tag or commit instead of a branch? Where can I find it?

Answer 1

A tag and branch are really just references to commits, with the main difference being a branch refers to a moving target (the latest commit on that branch), while a tag references a single point in time commit, but ultimately they are just pointing to a commit.

The tag_or_commit variable above could be renamed tag_or_branch_or_commit , or simply commit . I would argue that the variable name is somewhat misleading / confusing.

I find the most common usage of rebasing it to give a branch, which means to rebase the branch to the most recent commit. Providing a commit (or tag) will rebase up to that commit, and no further.

So the full command above is pulling from the origin, and then rebasing the commits that have happened up to the point that tag_or_commit is referring to. A use case might be if you wanted to rebase to what's been released to production, and you have a tag production_release , then if you were to execute:

git pull --rebase origin production_release

You would get all the commits up until the production_release tag, but no more.

Answer 2

Edit : based on your comments on the previous answer, you're just missing one thing: the git rebase step rebases the current branch , regardless of what arguments you've passed to git pull . You can probably skip all the rest of this!

---

It's actually in the git pull documentation , but in typical git documentation fashion, made extra-confusing:

<refspec> can name an arbitrary remote ref (for example, the name of a tag) or even a collection of refs with corresponding remote-tracking branches (eg, refs/heads/*:refs/remotes/origin/*), but usually it is the name of a branch in the remote repository.

What's missing is a thorough definition of a "refspec" along with a thorough description of the two parts that git pull runs. Unfortunately for the first part, refspecs appear in both fetch and push, but behave differently in them. It may suffice to say that for fetch purposes, normally you just name a branch or tag that exists on the remote, and git fetch copies it to your own repository but changes the name to a remote-tracking branch, such as origin/master , if it's a branch . For tags, it leaves the name unchanged. (More precisely, origin's refs/heads/master becomes refs/remote/origin/master in your repository, while its refs/tags/v1.2 stays refs/tags/v1.2 .)

The second part is perhaps a bit easier: git pull collects some flags and acts on them itself, and passes the rest of them to its first step, git fetch . One of the flags git pull collects is --rebase , which tells it to use git rebase as its second step. Otherwise, it looks to see if it's been configured to use git rebase automatically; if not, it defaults to using git merge .

In this case, then, given a tag name tag , git pull will: ¹

1. run git fetch origin tag
2. run git rebase tag

The fetch step will create a local tag if needed, fetching any corresponding commits and other objects if needed, or just be a glorified no-op if you already have the tag.

The second step is the especially-confusing bit. Passing a tag name to git rebase as its "upstream" argument seems weird. It is, however, well-defined and can make sense; and this is also described reasonably well in the git rebase documentation , provided you know the secret about rebase: it doesn't change any commits, it just copies some commits, then re-points your current branch.

First, git gets a list of commits that are contained within the current branch, ² excluding any commits reachable from the named upstream:

$ git rev-list tag..HEAD

Next, git gets onto a new anonymous branch starting with the commit identified by the --onto argument, or if there is no --onto , the commit identified by the "upstream" argument. In this case there is no --onto and the "upstream" argument is a tag, so git could simply check out the tag (it doesn't quite—it uses a general form that works for branch names as well—but it works out the same).

As its second to last step, the rebase "replays" each of the commits whose IDs are in the git rev-list output. Essentially, git cherry-picks each such commit into the new anonymous branch.

As the final step (if all has gone well, or after you've fixed things up and done git rebase --continue ), git moves the branch you were on ³ to point to the final commit made by coping all the to-be-copied commits. Assuming you were on a branch that originates somewhere "before" the tagged commit T , we can thus draw a graph of the final result like this:

    A - B - C            [abandoned]
  /
o - o - T - o - o         <-- somebranch
          \
           A' - B' - C'   <-- HEAD=yourbranch

Here A through C are your original commits that were on yourbranch before the git pull origin tag step, and A' through C' are their copies.

---

¹ This is still simplified, and git pull has evolved over time; the actual arguments can get pretty complex. None of that matters for this particular case, fortunately.

² This even works if you're on no branch at all: in that case git uses the anonymous branch defined by whatever commit-ID is in HEAD .

³ If you were not on a branch, that's even easier: it just skips this step entirely. HEAD still points to an anonymous branch, but now it's the copied one.