Merge pull request #1181 from rpjday/topic/rpjday/tagging

Tagging: Small amount of grammatical cleanup, enhance some explanations

Author: ben

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 [email protected]: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 <remote> --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 <tagname>`.
@@ -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 <remote> :refs/tags/<tagname>`:
+There are two common variations for deleting a tag from a remote server.
+
+The first variation is `git push <remote> :refs/tags/<tagname>`:
 
 [source,console]
 ----
@@ -238,9 +246,18 @@ To /[email protected]: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 <tagname>
+----
+
 ==== 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]
 ----