Git: Push Tags to a Remote Repo

If you've been using Git for any significant amount of time then you probably already know how to push your commits from a local branch to a remote repository. But, as you may be aware, Git doesn't just track commits, there are other objects/references as well, like tags.

These tags, which point to a specific spot in a repo's history, can also be pushed to remote repos for other developers to use or reference. Tags can be used for a lot of things, but the use-case I see the most is to use tags to mark the project's version number at a specific point in history.

In order to push them to a remote repo, you have a few options:

$ git push <repo-name> <tag-name>

This command will push a single tag to the remote repo, and it is commonly the preferred method, which I'll explain more about below.

The other way would be to push all of the tags to the remote repo:

$ git push --tags <repo-name>

This way is not recommended because it's common for developers to have old or "bad" tags in their local repositories that have no need to be in the remote one, so it's advised to only ever explicitly push a tag using the first method, and not all of your tags at once.

But what if you need to move a tag to a different commit? This typically happens when you accidentally tag the wrong commit or if you forget to merge changes to master before tagging. In this case, you'd want to do the following:

  • Delete the tag from the remote repo
  • Move the tag to the correct commit
  • Push the tag to the remote repo

In terms of Git commands, this is what that sequence would look like:

$ git push <repo-name> :refs/tags/<tag-name>
$ git tag -fa <tag-name> <commit-hash>
$ git push -f <repo-name> <tag-name>

The -f flag is shorthand for --force, which disables certain checks and allows references to change, for example.

You can also omit the <commit-hash> argument from the git tag command if you're tagging the most recent commit. Personally, I prefer to be explicit with my tag commands to make sure I always know exactly what I'm tagging, but you should do whatever works best for you.