Switch to another Git tag

Question

How do I check out version version/tag 1.1.4 of the rspec bundle?

cd ~/Library/Application\ Support/TextMate/Bundles/
git clone git://github.com/rspec/rspec-tmbundle.git RSpec.tmbundle
osascript -e 'tell app "TextMate" to reload bundles'

Answer 1

Clone the repository as normal:

git clone git://github.com/rspec/rspec-tmbundle.git RSpec.tmbundle

Then checkout the tag you want like so:

git checkout tags/1.1.4

This will checkout out the tag in a 'detached HEAD' state. In this state, "you can look around, make experimental changes and commit them, and [discard those commits] without impacting any branches by performing another checkout".

To retain any changes made, move them to a new branch:

git checkout -b 1.1.4-jspooner

You can get back to the master branch by using:

git checkout master

Note, as was mentioned in the first revision of this answer, there is another way to checkout a tag:

git checkout 1.1.4

But as was mentioned in a comment, if you have a branch by that same name, this will result in git warning you that the refname is ambiguous and checking out the branch by default:

warning: refname 'test' is ambiguous.
Switched to branch '1.1.4'

The shorthand can be safely used if the repository does not share names between branches and tags.

Answer 2

As of Git v2.23.0 (August 2019), git switch is preferred over git checkout when you’re simply switching branches/tags. I’m guessing they did this since git checkout had two functions: for switching branches and for restoring files. So in v2.23.0, they added two new commands, git switch, and git restore, to separate those concerns. I would predict at some point in the future, git checkout will be deprecated.

To switch to a normal branch, use git switch <branch-name>. To switch to a commit-like object, including single commits and tags, use git switch --detach <commitish>, where <commitish> is the tag name or commit number.

The --detach option forces you to recognize that you’re in a mode of “inspection and discardable experiments”. To create a new branch from the commitish you’re switching to, use git switch -c <new-branch> <start-point>.

Answer 3

chharvey's answer suggests

To switch to a commit-like object, including single commits and tags, use git switch --detach <commitish>, where <commitish> is the tag name or commit number.

Actually, Git 2.36 (Q2 2022) is clearer: the error message given by "git switch HEAD~4"^(man)" has been clarified to suggest the "--detach" option that is required.

See commit 808213b (25 Feb 2022) by Alex Henrie (alexhenrie).
^{(Merged by Junio C Hamano -- gitster -- in commit 061fd57, 06 Mar 2022)}

switch: mention the --detach option when dying due to lack of a branch

^{Signed-off-by: Alex Henrie}

Users who are accustomed to doing git checkout <tag>^(man) assume that git switch <tag>^(man) will do the same thing.
Inform them of the --detach option so they aren't left wondering why git switch doesn't work but git checkout does.

git config now includes in its man page:

suggestDetachingHead

Advice shown when git switch refuses to detach HEAD without the explicit --detach option.

The error message will show:

a branch is expected, got tag 'xxx'
If you want to detach HEAD at the commit, try again with the --detach option