diff --git a/book/02-git-basics/sections/tagging.asc b/book/02-git-basics/sections/tagging.asc index d468e18d4..a449b0a06 100644 --- a/book/02-git-basics/sections/tagging.asc +++ b/book/02-git-basics/sections/tagging.asc @@ -2,27 +2,27 @@ === Tagging (((tags))) -Like most VCSs, Git has the ability to tag specific points in history as being important. -Typically people use this functionality to mark release points (v1.0, and so on). -In this section, you'll learn how to list the available tags, how to create new tags, and what the different types of tags are. +Like most VCSs, Git has the ability to tag specific points in a repository's history as being important. +Typically, people use this functionality to mark release points (`v1.0`, `v2.0` and so on). +In this section, you'll learn how to list existing tags, how to create and delete tags, and what the different types of tags are. ==== Listing Your Tags -Listing the available tags in Git is straightforward. +Listing the existing tags in Git is straightforward. Just type `git tag` (with optional `-l` or `--list`):(((git commands, tag))) [source,console] ---- $ git tag -v0.1 -v1.3 +v1.0 +v2.0 ---- -This command lists the tags in alphabetical order; the order in which they appear has no real importance. +This command lists the tags in alphabetical order; the order in which they are displayed has no real importance. You can also search for tags that match a particular pattern. The Git source repo, for instance, contains more than 500 tags. -If you're only interested in looking at the 1.8.5 series, you can run this: +If you're interested only in looking at the 1.8.5 series, you can run this: [source,console] ---- @@ -217,6 +217,12 @@ To git@github.com:schacon/simplegit.git Now, when someone else clones or pulls from your repository, they will get all your tags as well. +[NOTE] +.`git push` pushes both types of tags +==== +Pushing tags using `git push --tags` does not distinguish between lightweight and annotated tags; there is no simple option that allows you to select just one type for pushing. +==== + ==== Deleting Tags To delete a tag on your local repository, you can use `git tag -d `. @@ -229,7 +235,9 @@ Deleted tag 'v1.4-lw' (was e7d5add) ---- Note that this does not remove the tag from any remote servers. -In order to update any remotes, you must use `git push :refs/tags/`: +There are two common variations for deleting a tag from a remote server. + +The first variation is `git push :refs/tags/`: [source,console] ---- @@ -238,9 +246,18 @@ To /git@github.com:schacon/simplegit.git - [deleted] v1.4-lw ---- +The way to interpret the above is to read it as the null value before the colon is being pushed to the remote tag name, effectively deleting it. + +The second (and more intuitive) way to delete a remote tag is with: + +[source,console] +---- +$ git push origin --delete +---- + ==== Checking out Tags -If you want to view the versions of files a tag is pointing to, you can do a git checkout, though this puts your repository in ``detached HEAD'' state, which has some ill side effects: +If you want to view the versions of files a tag is pointing to, you can do a `git checkout` of that tag, although this puts your repository in ``detached HEAD'' state, which has some ill side effects: [source,console] ----