How do I create tag with certain commits and push it to origin?

Question

Say the current log in my gerrit looks like the following:

• commit10 (master)
• commit9
• commit8
• commit7
• commit6 v1.72.0
• commit5
• commit4 v1.71.0
• commit3
• commit2
• commit1

My goal is to create a new tag (v1.73.0) that should contain commit8 and commit9 and push it to origin. I was told to create a new local branch based on the latest stable tag and cherry-pick the necessary commits and tag it up. However, I am having some problem pushing the tag up to master.

Here's what I've done:

• create local branch based on the latest tag: git checkout -b branchforv1.73.0 v1.72.0
• cherry-pick commit8 and commit9
• create new tag: git tag v1.73.0

...so now, how do I push v1.73.0 to master?

Result:

• commit10 (master)
• commit7
• commit9 v1.73.0
• commit8
• commit6 v1.72.0
• commit5
• commit4 v1.71.0
• commit3
• commit2
• commit1

Answer 1

How tags work

In git, each tag is said to "point to" a (one, single) commit. In fact, the same is true of a branch: a branch name also just points to one commit.

What makes this work is two things:

• each commit also points to another commit (or perhaps several), and
• for branches (and only for branches), the commit to which the branch points "moves forward" automatically. That is, as you add new commits—in some ways, that's mostly all git does: add new commits to its collective, sort of like the Borg from the old Star Trek TNG series—whatever branch you're on, that's the branch that gets re-adjusted to point to the new commit.

Thus, the main difference between a branch and a tag is that a tag does not move.

To see how this works, consider a simple git repository with just three commits. Let's label these commits A, B, and C. The first commit (A) points to nothing, as it's the first commit, and branch master points to A:

A   <-- master 

When you make the second commit, git creates B pointing back to A, and advances the branch name to point to B:

A <- B   <-- master 

Then when you make a third commit, git again makes it point back to its parent commit, and advances the branch:

A <- B <- C   <-- master 

If you make a tag now, that tag will, by default, point to commit C:

A <- B <- C   <-- master           ^           |    tag: sometag 

If you then make a new commit D, git advances the branch, but not the tag:

A <- B <- C <- D   <-- master           ^           |    tag: sometag 

You can, at any time, create or delete any tag pointing to any particular commit:

$ git tag -d sometag 

will delete tag sometag, after which:

$ git tag sometag master~2 

will add sometag pointing to commit B.¹

(We've just proven that a tag can move. The real difference is that tags are not expected to move, while branches are; and git won't move tags automatically.² Branches are generally expected to move in a "forward" direction, i.e., if master used to point to commit C and now points to commit D, commit C should usually be found by starting at D and working backwards. Any time you move a branch so that this rule is violated, you're "rewriting history"; see other articles for when this is fine, and when it causes people trouble.)

Pushing tags

When you use git push, what you're really doing is instructing some other git repository to take any new commits you have that they don't, and then set some name(s)—usually branches and/or tags—to point to some commits (one each) in the resulting collection.³ These names (branches, tags, and so on) are called "references" in general, but let's just use "branch" and "tag" for now.

The argument after git push names the repository (generally via a "remote" name, like origin) to push-to. If you leave it out, git will try to figure one out, but if you want to add a branch or tag name, you need to include it explicitly, since the first word here is assumed to be the remote-name. (That is, git push master tries to use master as a remote-name rather than a branch-name.)

To push all your tags, you can simply add --tags to your git push command:

git push --tags origin 

To push a specific tag, you can name it:

git push origin sometag 

just as you can push a specific branch:

git push origin master 

(In fact, that fourth argument is a pair of names, like master:master or sometag:sometag, but it defaults to using the same name on both sides in most cases.⁴)

You can leave out the name origin if you don't need it to make all the arguments, e.g., git push --tags is the same as git push --tags origin (assuming all your pushes go to origin, anyway).

Putting it together

To set a tag in the remote, first set it locally, with git tag name commit-identifier. Use whatever viewer you like to make sure it's set correctly. Then push it, with either git push origin name or git push --tags.

---

¹The master~2 syntax instructs git to start at the commit found via master, then back up two steps. You could instead write the raw SHA-1 for commit B here.

²Old versions of git (pre 1.8.4) accidentally applied branch rules to tags when pushing (on the remote side, i.e., they let a tag move if it was a "fast forward").

³In some cases, you can point a name to an "annotated tag", and there's nothing preventing a name from pointing at a "tree" or "blob" object either, but that's not a normal setup.

⁴Actually the default dst refspec for a branch is complicated: it depends on your push.default configuration, and whether there is a remote.repository.push setting, and whether there is an upstream configured, and so on. For tags, the rules are simpler since there's no such thing as an "upstream".