Update documentation of hg tag

# HG changeset patch
# User Radoslaw Szkodzinski <[e-mail]>
# Node ID 8fc9bfabae06cba91b05c265545bcce2654dab2f
# Parent  7369ec5d93f2ffd490a43970edd9adf8d2bbe269
Update documentation of hg tag

This updates the FAQ, manpage and adds hg tag to the list of commands
in README.

Index: hg/README
===================================================================

README

@@ -1,124 +1,126 b''
 MERCURIAL QUICK-START
 
 Setting up Mercurial:
 
  Note: some distributions fails to include bits of distutils by
  default, you'll need python-dev to install. You'll also need a C
  compiler and a 3-way merge tool like merge, tkdiff, or kdiff3.
 
  First, unpack the source:
 
  $ tar xvzf mercurial-<ver>.tar.gz
  $ cd mercurial-<ver>
 
  To install system-wide:
 
  $ python setup.py install   # change python to python2.3 if 2.2 is default
 
  To install in your home directory (~/bin and ~/lib, actually), run:
 
  $ python2.3 setup.py install --home=~
  $ export PYTHONPATH=${HOME}/lib/python  # (or lib64/ on some systems)
  $ export PATH=${HOME}/bin:$PATH         # add these to your .bashrc
 
  And finally:
 
  $ hg                                    # test installation, show help
 
  If you get complaints about missing modules, you probably haven't set
  PYTHONPATH correctly.
 
 Setting up a Mercurial project:
 
  $ cd project/
  $ hg init         # creates .hg
  $ hg status       # show changes between repo and working dir
  $ hg diff         # generate a unidiff
  $ hg addremove    # add all unknown files and remove all missing files
  $ hg commit       # commit all changes, edit changelog entry
  $ hg export <rev> # export a changeset as a diff
 
  Mercurial will look for a file named .hgignore in the root of your
  repository contains a set of regular expressions to ignore in file
  paths.
 
 Mercurial commands:
 
  $ hg help [command]   # get online help
  $ hg history          # show changesets
  $ hg log Makefile     # show commits per file
  $ hg update           # check out the tip revision
  $ hg update <id>      # check out a specified changeset
                        # IDs can be tags, revision numbers, or unique
                        # subsets of changeset hash numbers
  $ hg add foo          # add a new file for the next commit
  $ hg remove bar       # mark a file as removed
  $ hg verify           # check repo integrity
  $ hg tags             # show current tags
+ $ hg tag <name>       # tag current tip with distributed tag <name>
+ $ hg tag -l <name>    # tag current tip with local tag <name>
  $ hg annotate [files] # show changeset numbers for each file line
 
 Branching and merging:
 
  $ cd ..
  $ mkdir linux-work
  $ cd linux-work
  $ hg init ../linux          # create a new branch
  $ hg update                 # populate the working directory
  $ <make changes>
  $ hg commit
  $ cd ../linux
  $ hg pull ../linux-work     # pull changesets from linux-work
  $ hg update -m              # merge the new tip from linux-work into
                              # our working directory
 
 Importing patches:
 
  Fast:
  $ patch < ../p/foo.patch
  $ hg addremove
  $ hg commit
 
  Faster:
  $ patch < ../p/foo.patch
  $ hg commit `lsdiff -p1 ../p/foo.patch`
 
  Fastest:
  $ cat ../p/patchlist | xargs hg import -p1 -b ../p 
 
 Exporting a patch:
 
  (make changes)
  $ hg commit
  $ hg tip
  28237:747a537bd090880c29eae861df4d81b245aa0190
  $ hg export 28237 > foo.patch    # export changeset 28237
 
 Network support:
 
  # pull from the primary Mercurial repo
  foo$ hg init
  foo$ hg pull http://selenic.com/hg/
  foo$ hg update # hg co works too
 
  # export your current repo via HTTP with browsable interface
  foo$ hg serve -n "My repo" -p 80
  
  # pushing changes to a remote repo with SSH
  foo$ hg push ssh://[e-mail]/~/hg/
 
  # merge changes from a remote machine
  bar$ hg pull http://foo/
  bar$ hg update -m        # merge changes into your working directory
 
  # Set up a CGI server on your webserver
  foo$ cp hgweb.cgi ~/public_html/hg/index.cgi
  foo$ emacs ~/public_html/hg/index.cgi # adjust the defaults
 
 Symbolic repository names:
 
  Mercurial uses an options file called ~/.hgrc. To track locations
  symbolically, add a section to it like this:
 
  [paths]
  main = http://selenic.com/hg
  linux = http://www.kernel.org/hg/

doc/FAQ.txt

@@ -1,317 +1,317 b''
 Mercurial Frequently Asked Questions
 ====================================
 
 Section 1: General Usage
 ------------------------
 
 .Q. I did an "hg pull" and my working directory is empty!
 
 There are two parts to Mercurial: the repository and the working
 directory. "hg pull" pulls all new changes from a remote repository
 into the local one but doesn't alter the working directory.
 
 This keeps you from upsetting your work in progress, which may not be
 ready to merge with the new changes you've pulled and also allows you
 to manage merging more easily (see below about best practices).
 
 To update your working directory, run "hg update". If you're sure you
 want to update your working directory on a pull, you can also use "hg
 pull -u". This will refuse to merge or overwrite local changes.
 
 
 .Q. What are revision numbers, changeset IDs, and tags?
 
 Mercurial will generally allow you to refer to a revision in three
 ways: by revision number, by changeset ID, and by tag.
 
 A revision number is a simple decimal number that corresponds with the
 ordering of commits in the local repository. It is important to
 understand that this ordering can change from machine to machine due
 to Mercurial's distributed, decentralized architecture.
 
 This is where changeset IDs come in. A changeset ID is a 160-bit
 identifier that uniquely describes a changeset and its position in the
 change history, regardless of which machine it's on. This is
 represented to the user as a 40 digit hexadecimal number. As that
 tends to be unwieldy, Mercurial will accept any unambiguous substring
 of that number when specifying versions. It will also generally print
 these numbers in "short form", which is the first 12 digits.
 
 You should always use some form of changeset ID rather than the local
 revision number when discussing revisions with other Mercurial users
 as they may have different revision numbering on their system.
 
 Finally, a tag is an arbitrary string that has been assigned a
 correspondence to a changeset ID. This lets you refer to revisions
 symbolically.
 
 
 .Q. What are branches, heads, and the tip?
 
 The central concept of Mercurial is branching. A 'branch' is simply
 an independent line of development. In most other version control
 systems, all users generally commit to the same line of development
 called 'the trunk' or 'the main branch'. In Mercurial, every developer
 effectively works on a private branch and there is no internal concept
 of 'the main branch'.
 
 Thus Mercurial works hard to make repeated merging between branches
 easy. Simply run "hg pull" and "hg update -m" and commit the result.
 
 'Heads' are simply the most recent commits on a branch. Technically,
 they are changesets which have no children. Merging is the process of
 joining points on two branches into one, usually at their current
 heads. Use "hg heads" to find the heads in the current repository.
 
 The 'tip' is the most recently changed head, and also the highest
 numbered revision. If you have just made a commit, that commit will be
 the head. Alternately, if you have just pulled from another
 repository, the tip of that repository becomes the current tip.
 
 The 'tip' is the default revision for many commands such as update,
 and also functions as a special symbolic tag.
 
 
 .Q. How does merging work?
 
 The merge process is simple. Usually you will want to merge the tip
 into your working directory. Thus you run "hg update -m" and Mercurial
 will incorporate the changes from tip into your local changes.
 
 The first step of this process is tracing back through the history of
 changesets and finding the 'common ancestor' of the two versions that
 are being merged. This is done on a project-wide and a file by file
 basis.
 
 For files that have been changed in both projects, a three-way merge
 is attempted to add the changes made remotely into the changes made
 locally. If there are conflicts between these changes, the user is
 prompted to interactively resolve them.
 
 Mercurial uses a helper tool for this, which is usually found by the
 hgmerge script. Example tools include tkdiff, kdiff3, and the classic
 RCS merge.
 
 After you've completed the merge and you're satisfied that the results
 are correct, it's a good idea to commit your changes. Mercurial won't
 allow you to perform another merge until you've done this commit as
 that would lose important history that will be needed for future
 merges.
 
 
 .Q. How do tags work in Mercurial?
 
 Tags work slightly differently in Mercurial than most revision
 systems. The design attempts to meet the following requirements:
 
 - be version controlled and mergeable just like any other file
 - allow signing of tags
 - allow adding a tag to an already committed changeset
 - allow changing tags in the future
 
 Thus Mercurial stores tags as a file in the working dir. This file is
 called .hgtags and consists of a list of changeset IDs and their
 corresponding tags. To add a tag to the system, simply add a line to
 this file and then commit it for it to take effect. The "hg tag"
 command will do this for you and "hg tags" will show the currently
 effective tags.
 
 Note that because tags refer to changeset IDs and the changeset ID is
 effectively the sum of all the contents of the repository for that
 change, it is impossible in Mercurial to simultaneously commit and add
 a tag. Thus tagging a revision must be done as a second step.
 
 
 .Q. What if I want to just keep local tags?
 
-You can add a section called "[tags]" to your .hg/hgrc which contains
-a list of tag = changeset ID pairs. Unlike traditional tags, these are
-only visible in the local repository, but otherwise act just like
-normal tags.
+You can use "hg tag" command with an option "-l" or "--local". This
+will store the tag in the file .hg/localtags, which will not be
+distributed or versioned. The format of this file is identical to the
+one of .hgtags and the tags stored there are handled the same.
 
 
 .Q. How do tags work with multiple heads?
 
 The tags that are in effect at any given time are the tags specified
 in each head, with heads closer to the tip taking precedence. Local
 tags override all other tags.
 
 
 .Q. What are some best practices for distributed development with Mercurial?
 
 First, merge often! This makes merging easier for everyone and you
 find out about conflicts (which are often rooted in incompatible
 design decisions) earlier.
 
 Second, don't hesitate to use multiple trees locally. Mercurial makes
 this fast and light-weight. Typical usage is to have an incoming tree,
 an outgoing tree, and a separate tree for each area being worked on.
 
 The incoming tree is best maintained as a pristine copy of the
 upstream repository. This works as a cache so that you don't have to
 pull multiple copies over the network. No need to check files out here
 as you won't be changing them.
 
 The outgoing tree contains all the changes you intend for merger into
 upsteam. Publish this tree with 'hg serve" or hgweb.cgi or use 'hg
 push" to push it to another publicly availabe repository.
 
 Then, for each feature you work on, create a new tree. Commit early
 and commit often, merge with incoming regularly, and once you're
 satisfied with your feature, pull the changes into your outgoing tree.
 
 
 .Q. How do I import from a repository created in a different SCM?
 
 Take a look at contrib/convert-repo. This is an extensible
 framework for converting between repository types.
 
 
 .Q. What about Windows support?
 
 Patches to support Windows are being actively integrated, a fully
 working Windows version is probably not far off
 
 
 Section 2: Bugs and Features
 ----------------------------
 
 .Q. I found a bug, what do I do?
 
 Report it to the mercurial mailing list, [e-mail].
 
 
 .Q. What should I include in my bug report?
 
 Enough information to reproduce or diagnose the bug. If you can, try
 using the hg -v and hg -d switches to figure out exactly what
 Mercurial is doing.
 
 If you can reproduce the bug in a simple repository, that is very
 helpful. The best is to create a simple shell script to automate this
 process, which can then be added to our test suite.
 
 
 .Q. Can Mercurial do <x>?
 
 If you'd like to request a feature, send your request to
 [e-mail]. As Mercurial is still very new, there are
 certainly features it is missing and you can give up feedback on how
 best to implement them.
 
 
 Section 3: Technical
 --------------------
 
 .Q. What limits does Mercurial have?
 
 Mercurial currently assumes that single files, indices, and manifests
 can fit in memory for efficiency.
 
 Offsets in revlogs are currently tracked with 32 bits, so a revlog for
 a single file can currently not grow beyond 4G.
 
 There should otherwise be no limits on file name length, file size,
 file contents, number of files, or number of revisions.
 
 The network protocol is big-endian.
 
 File names cannot contain the null character. Committer addresses
 cannot contain newlines.
 
 Mercurial is primarily developed for UNIX systems, so some UNIXisms
 may be present in ports.
 
 
 .Q. How does Mercurial store its data?
 
 The fundamental storage type in Mercurial is a "revlog". A revlog is
 the set of all revisions of a named object. Each revision is either
 stored compressed in its entirety or as a compressed binary delta
 against the previous version. The decision of when to store a full
 version is made based on how much data would be needed to reconstruct
 the file. This lets us ensure that we never need to read huge amounts
 of data to reconstruct a object, regardless of how many revisions of it
 we store.
 
 In fact, we should always be able to do it with a single read,
 provided we know when and where to read. This is where the index comes
 in. Each revlog has an index containing a special hash (nodeid) of the
 text, hashes for its parents, and where and how much of the revlog
 data we need to read to reconstruct it. Thus, with one read of the
 index and one read of the data, we can reconstruct any version in time
 proportional to the object size.
 
 Similarly, revlogs and their indices are append-only. This means that
 adding a new version is also O(1) seeks.
 
 Revlogs are used to represent all revisions of files, manifests, and
 changesets. Compression for typical objects with lots of revisions can
 range from 100 to 1 for things like project makefiles to over 2000 to
 1 for objects like the manifest.
 
 
 .Q. How are manifests and changesets stored?
 
 A manifest is simply a list of all files in a given revision of a
 project along with the nodeids of the corresponding file revisions. So
 grabbing a given version of the project means simply looking up its
 manifest and reconstruction all the file revisions pointed to by it.
 
 A changeset is a list of all files changed in a check-in along with a
 change description and some metadata like user and date. It also
 contains a nodeid to the relevent revision of the manifest.
 
 
 .Q. How do Mercurial hashes get calculated?
 
 Mercurial hashes both the contents of an object and the hash of its
 parents to create an identifier that uniquely identifies an object's
 contents and history. This greatly simplifies merging of histories
 because it avoid graph cycles that can occur when a object is reverted
 to an earlier state.
 
 All file revisions have an associated hash value. These are listed in
 the manifest of a given project revision, and the manifest hash is
 listed in the changeset. The changeset hash is again a hash of the
 changeset contents and its parents, so it uniquely identifies the
 entire history of the project to that point.
 
 
 .Q. What checks are there on repository integrity?
 
 Every time a revlog object is retrieved, it is checked against its
 hash for integrity. It is also incidentally doublechecked by the
 Adler32 checksum used by the underlying zlib compression.
 
 Running 'hg verify' decompresses and reconstitutes each revision of
 each object in the repository and cross-checks all of the index
 metadata with those contents.
 
 But this alone is not enough to ensure that someone hasn't tampered
 with a repository. For that, you need cryptographic signing.
 
 
 .Q. How does signing work with Mercurial?
 
 Take a look at the hgeditor script for an example. The basic idea is
 to use GPG to sign the manifest ID inside that changelog entry. The
 manifest ID is a recursive hash of all of the files in the system and
 their complete history, and thus signing the manifest hash signs the
 entire project contents.
 
 
 .Q. What about hash collisions? What about weaknesses in SHA1?
 
 The SHA1 hashes are large enough that the odds of accidental hash collision
 are negligible for projects that could be handled by the human race.
 The known weaknesses in SHA1 are currently still not practical to
 attack, and Mercurial will switch to SHA256 hashing before that
 becomes a realistic concern.
 
 Collisions with the "short hashes" are not a concern as they're always
 checked for ambiguity and are still long enough that they're not
 likely to happen for reasonably-sized projects (< 1M changes).
 
 
 

doc/hg.1.txt

@@ -1,591 +1,592 b''
 HG(1)
 =====
 Matt Mackall <[e-mail]>
 
 NAME
 ----
 hg - Mercurial source code management system
 
 SYNOPSIS
 --------
 'hg' [-v -d -q -y] <command> [command options] [files]
 
 DESCRIPTION
 -----------
 The hg(1) command provides a command line interface to the Mercurial system.
 
 OPTIONS
 -------
 
 --debug, -d::
     enable debugging output
 
 --quiet, -q::
     suppress output
 
 --verbose, -v::
     enable additional output
 
 --noninteractive, -y::
     do not prompt, assume 'yes' for any required answers
 
 COMMAND ELEMENTS
 ----------------
 
 files ...::
     indicates one or more filename or relative path filenames
 
 path::
     indicates a path on the local machine
 
 revision::
     indicates a changeset which can be specified as a changeset revision
     number, a tag, or a unique substring of the changeset hash value
 
 repository path::
     either the pathname of a local repository or the URI of a remote
     repository.  There are two available URI protocols, http:// which is
     fast and the old-http:// protocol which is much slower but does not
     require a special server on the web host.
 
 COMMANDS
 --------
 
 add [files ...]::
     Schedule files to be version controlled and added to the repository.
     
     The files will be added to the repository at the next commit.
 
 addremove::
     Add all new files and remove all missing files from the repository.
     
     New files are ignored if they match any of the patterns in .hgignore. As
     with add, these changes take effect at the next commit.
 
 annotate [-r <rev> -u -n -c] [files ...]::
     List changes in files, showing the revision id responsible for each line
     
     This command is useful to discover who did a change or when a change took
     place.
     
     options:
     -r, --revision <rev>  annotate the specified revision
     -u, --user            list the author
     -c, --changeset       list the changeset
     -n, --number          list the revision number (default)
 
 cat <file> [revision]::
     Output to stdout the given revision for the specified file.
 
     If no revision is given then the tip is used.
 
 clone [-U] <source> [dest]::
     Create a copy of an existing repository in a new directory.
 
     If no destination directory name is specified, it defaults to the
     basename of the source.
 
     The source is added to the new repository's .hg/hgrc file to be used in
     future pulls.
 
     For efficiency, hardlinks are used for cloning whenever the
     source and destination are on the same filesystem.
 
     options:
     -U, --noupdate   do not update the new working directory
 
 commit [-A -t -l <file> -t <text> -u <user> -d <datecode>] [files...]::
     Commit changes to the given files into the repository.
     
     If a list of files is omitted, all changes reported by "hg status"
     will be commited.
     
     The HGEDITOR or EDITOR environment variables are used to start an
     editor to add a commit comment.
 
     Options:
 
     -A, --addremove       run addremove during commit
     -t, --text <text>     use <text> as commit message
     -l, --logfile <file>  show the commit message for the given file
     -d, --date <datecode> record datecode as commit date
     -u, --user <user>     record user as commiter
 
     aliases: ci
 
 copy <source> <dest>::
     Mark <dest> file as a copy or rename of a <source> one
     
     This command takes effect for the next commit.
 
 diff [-r revision] [-r revision] [files ...]::
     Show differences between revisions for the specified files.
     
     Differences between files are shown using the unified diff format.
     
     When two revision arguments are given, then changes are shown
     between those revisions. If only one revision is specified then
     that revision is compared to the working directory, and, when no
     revisions are specified, the working directory files are compared
     to its parent.
 
 export [-o filespec] [revision] ...::
     Print the changeset header and diffs for one or more revisions.
 
     The information shown in the changeset header is: author,
     changeset hash, parent and commit comment.
 
     Output may be to a file, in which case the name of the file is
     given using a format string.  The formatting rules are as follows:
 
     %%   literal "%" character
     %H   changeset hash (40 bytes of hexadecimal)
     %N   number of patches being generated
     %R   changeset revision number
     %b   basename of the exporting repository
     %h   short-form changeset hash (12 bytes of hexadecimal)
     %n   zero-padded sequence number, starting at 1
     %r   zero-padded changeset revision number
 
     Options:
 
     -o, --output <filespec>   print output to file with formatted named
 
 forget [files]::
     Undo an 'hg add' scheduled for the next commit.
 
 heads::
     Show all repository head changesets.
     
     Repository "heads" are changesets that don't have children
     changesets. They are where development generally takes place and
     are the usual targets for update and merge operations.
 
 identify::
     Print a short summary of the current state of the repo.
     
     This summary identifies the repository state using one or two parent
     hash identifiers, followed by a "+" if there are uncommitted changes
     in the working directory, followed by a list of tags for this revision.
 
     aliases: id
 
 import [-p <n> -b <base> -q] <patches>::
     Import a list of patches and commit them individually.
 
     options:
     -p, --strip <n>   directory strip option for patch. This has the same
                       meaning as the correnponding patch option
     -b <path>         base directory to read patches from
 
     aliases: patch
 
 init::
     Initialize a new repository in the current directory.
 
 locate [options] [patterns]::
     Print all files under Mercurial control whose basenames match the
     given patterns.
 
     Patterns are shell-style globs.  To restrict searches to specific
     directories, use the "-i <pat>" option.  To eliminate particular
     directories from searching, use the "-x <pat>" option.
 
     This command searches the current directory and its
     subdirectories.  To search an entire repository, move to the root
     of the repository.
 
     If no patterns are given to match, this command prints all file
     names.
 
     If you want to feed the output of this command into the "xargs"
     command, use the "-0" option to both this command and "xargs".
     This will avoid the problem of "xargs" treating single filenames
     that contain white space as multiple file names.
 
     options:
 
     -0, --print0         end filenames with NUL, for use with xargs
     -f, --fullpath       print complete paths from the filesystem root
     -i, --include <pat>  include directories matching the given globs
     -r, --rev <rev>      search the repository as it stood at rev
     -x, --exclude <pat>  exclude directories matching the given globs
 
 log [-r revision ...] [-p] [file]::
     Print the revision history of the specified file or the entire project.
 
     By default this command outputs: changeset id and hash, tags,
     parents, user, date and time, and a summary for each commit. The
     -v switch adds some more detail, such as changed files, manifest
     hashes or message signatures.
 
     options:
     -r, --rev <A>, ...  When a revision argument is given, only this file or
                         changelog revision is displayed. With two revision
                         arguments all revisions in this range are listed.
                         Additional revision arguments may be given repeating
                         the above cycle.
     -p, --patch         show patch
 
     aliases: history
 
 manifest [revision]::
     Print a list of version controlled files for the given revision.
 
     The manifest is the list of files being version controlled. If no revision
     is given then the tip is used.
 
 parents::
     Print the working directory's parent revisions.
 
 pull <repository path>::
     Pull changes from a remote repository to a local one.
 
     This finds all changes from the repository at the specified path
     or URL and adds them to the local repository. By default, this
     does not update the copy of the project in the working directory.
 
     options:
     -u, --update   update the working directory to tip after pull
 
 push <destination>::
     Push changes from the local repository to the given destination.
     
     This is the symmetrical operation for pull. It helps to move
     changes from the current repository to a different one. If the
     destination is local this is identical to a pull in that directory
     from the current one.
 
     The other currently available push method is SSH. This requires an
     accessible shell account on the destination machine and a copy of
     hg in the remote path. Destinations are specified in the following
     form:
 
       ssh://[user@]host[:port]/path
 
 rawcommit [-p -d -u -F -t -l]::
     Lowlevel commit, for use in helper scripts.
     
     This command is not intended to be used by normal users, as it is
     primarily useful for importing from other SCMs.
 
 recover::
     Recover from an interrupted commit or pull.
     
     This command tries to fix the repository status after an interrupted
     operation. It should only be necessary when Mercurial suggests it.
 
 remove [files ...]::
     Schedule the indicated files for removal from the repository.
     
     This command shedules the files to be removed at the next commit.
     This only removes files from the current branch, not from the
     entire project history.
 
     aliases: rm
 
 revert [names ...]::
     Revert any uncommitted modifications made to the named files or
     directories.  This restores the contents of the affected files to
     an unmodified state.
 
     If a file has been deleted, it is recreated.  If the executable
     mode of a file was changed, it is reset.
 
     If a directory is given, all files in that directory and its
     subdirectories are reverted.
 
     If no arguments are given, all files in the current directory and
     its subdirectories are reverted.
 
     options:
     -r, --rev <rev>       revision to revert to
     -n, --nonrecursive    do not recurse into subdirectories
 
 root::
     Print the root directory of the current repository.
 
 serve [options]::
     Start a local HTTP repository browser and pull server.
 
     By default, the server logs accesses to stdout and errors to
     stderr.  Use the "-A" and "-E" options to log to files.
 
     options:
     -A, --accesslog <file>   name of access log file to write to
     -E, --errorlog <file>    name of error log file to write to
     -a, --address <addr>     address to use
     -p, --port <n>           port to use (default: 8000)
     -n, --name <name>        name to show in web pages (default: working dir)
     -t, --templatedir <path> web templates to use
 
 status::
     Show changed files in the working directory.
 
     The codes used to show the status of files are:
     
     C = changed
     A = added
     R = removed
     ? = not tracked
 
-tag [-t <text> -d <datecode> -u <user>] <name> [revision]::
+tag [-l -t <text> -d <datecode> -u <user>] <name> [revision]::
     Name a particular revision using <name>.
     
     Tags are used to name particular revisions of the repository and are
     very useful to compare different revision, to go back to significant
     earlier versions or to mark branch points as releases, etc.
     
     If no revision is given, the tip is used.
 
     To facilitate version control, distribution, and merging of tags,
     they are stored as a file named ".hgtags" which is managed
     similarly to other project files and can be hand-edited if
     necessary.
 
     options:
+    -l, --local           make the tag local
     -t, --text <text>     message for tag commit log entry
     -d, --date <datecode> datecode for commit
     -u, --user <user>     user for commit
 
-    Note: Mercurial also has support for "local tags" that are not
-    version-controlled or distributed which are stored in the .hg/hgrc
-    file.
+    Note: Local tags are not version-controlled or distributed and are
+    stored in the .hg/localtags file. If there exists a local tag and
+    a public tag with the same name, local tag is used.
 
 tags::
     List the repository tags.
 
     This lists both regular and local tags.
 
 tip::
     Show the tip revision.
 
 undo::
     Undo the last commit or pull transaction.
 
     Roll back the last pull or commit transaction on the
     repository, restoring the project to its earlier state.
 
     This command should be used with care. There is only one level of
     undo and there is no redo.
 
     This command is not intended for use on public repositories. Once
     a change is visible for pull by other users, undoing it locally is
     ineffective.
 
 update [-m -C] [revision]::
     Update the working directory to the specified revision.
 
     By default, update will refuse to run if doing so would require
     merging or discarding local changes.
 
     With the -m option, a merge will be performed.
 
     With the -C option, local changes will be lost.
     
     options:
     -m, --merge       allow merging of branches
     -C, --clean       overwrite locally modified files
 
     aliases: up checkout co
 
 verify::
     Verify the integrity of the current repository.
 
     This will perform an extensive check of the repository's
     integrity, validating the hashes and checksums of each entry in
     the changelog, manifest, and tracked files, as well as the
     integrity of their crosslinks and indices.
 
 SPECIFYING SINGLE REVISIONS
 ---------------------------
 
     Mercurial accepts several notations for identifying individual
     revisions.
 
     A plain integer is treated as a revision number.  Negative
     integers are treated as offsets from the tip, with -1 denoting the
     tip.
 
     A 40-digit hexadecimal string is treated as a unique revision
     identifier.
 
     A hexadecimal string less than 40 characters long is treated as a
     unique revision identifier, and referred to as a short-form
     identifier.  A short-form identifier is only valid if it is the
     prefix of one full-length identifier.
 
     Any other string is treated as a tag name, which is a symbolic
     name associated with a revision identifier.  Tag names may not
     contain the ":" character.
 
     The reserved name "tip" is a special tag that always identifies
     the most recent revision.
 
 SPECIFYING MULTIPLE REVISIONS
 -----------------------------
 
     When Mercurial accepts more than one revision, they may be
     specified individually, or provided as a continuous range,
     separated by the ":" character.
 
     The syntax of range notation is [BEGIN]:[END], where BEGIN and END
     are revision identifiers.  Both BEGIN and END are optional.  If
     BEGIN is not specified, it defaults to revision number 0.  If END
     is not specified, it defaults to the tip.  The range ":" thus
     means "all revisions".
 
     If BEGIN is greater than END, revisions are treated in reverse
     order.
 
     A range acts as an open interval.  This means that a range of 3:5
     gives 3, 4 and 5.  Similarly, a range of 4:2 gives 4, 3, and 2.
 
 ENVIRONMENT VARIABLES
 ---------------------
 
 HGEDITOR::
     This is the name of the editor to use when committing. Defaults to the
     value of EDITOR. 
 
     (deprecated, use .hgrc)
 
 HGMERGE::
     An executable to use for resolving merge conflicts. The program
     will be executed with three arguments: local file, remote file,
     ancestor file.
 
     The default program is "hgmerge", which is a shell script provided
     by Mercurial with some sensible defaults.
 
     (deprecated, use .hgrc)
 
 HGUSER::
     This is the string used for the author of a commit.
 
     (deprecated, use .hgrc)
 
 EMAIL::
     If HGUSER is not set, this will be used as the author for a commit.
 
 LOGNAME::
     If neither HGUSER nor EMAIL is set, LOGNAME will be used (with
     '@hostname' appended) as the author value for a commit.
 
 EDITOR::
     This is the name of the editor used in the hgmerge script. It will be
     used for commit messages if HGEDITOR isn't set. Defaults to 'vi'.
 
 PYTHONPATH::
     This is used by Python to find imported modules and may need to be set
     appropriately if Mercurial is not installed system-wide.
 
 FILES
 -----
  .hgignore::
     This file contains regular expressions (one per line) that describe file
     names that should be ignored by hg.
 
  .hgtags::
     This file contains changeset hash values and text tag names (one of each
     seperated by spaces) that correspond to tagged versions of the repository
     contents.
 
  $HOME/.hgrc, .hg/hgrc::
     This file contains defaults and configuration. Values in .hg/hgrc
     override those in .hgrc.
 
 
 UI OPTIONS
 ----------
 
 Various configuration options can be set in .hgrc:
 
 -------------
 [ui]
 verbose = 0
 username = Matt Mackall <[e-mail]>
 editor = hgeditor
 merge = hgmerge
 -------------
 
 
 NAMED REPOSITORIES
 ------------------
 
 To give symbolic names to a repository, create a section in .hgrc
 or .hg/hgrc containing assignments of names to paths. Example:
 
 -----------------
 [paths]
 hg = http://selenic.com/hg
 tah = http://hg.intevation.org/mercurial-tah/
 -----------------
 
 
 LOCAL TAGS
 ----------
 
 To create tags that are local to the repository and not distributed or
 version-controlled, create an hgrc section like the following:
 
 ----------------
 [tags]
 working = 2dcced388cab3677a8f543c3c47a0ad34ac9d435
 tested = 12e0fdbc57a0be78f0e817fd1d170a3615cd35da
 ----------------
 
 
 HOOKS
 -----
 
 Mercurial supports a set of 'hook', commands that get automatically
 executed by various actions such as starting or finishing a commit. To
 specify a hook, simply create an hgrc section like the following:
 
 -----------------
 [hooks]
 precommit = echo "this hook gets executed immediately before a commit"
 commit = hg export $NODE | mail -s "new commit $NODE" commit-list
 -----------------
 
 
 NON_TRANSPARENT PROXY SUPPORT
 -----------------------------
 
 To access a Mercurial repository through a proxy, create a file
 $HOME/.hgrc in the following format:
 
 --------------
 [http_proxy]
 host=myproxy:8080
 user=<username>
 passwd=<password>
 no=<localhost1>,<localhost2>,<localhost3>,...
 --------------
 
 "user" and "passwd" fields are used for authenticating proxies, "no" is a
 comma-separated list of local host names to not proxy.
 
 BUGS
 ----
 Probably lots, please post them to the mailing list (See Resources below)
 when you find them.
 
 AUTHOR
 ------
 Written by Matt Mackall <[e-mail]>
 
 RESOURCES
 ---------
 http://selenic.com/mercurial[Main Web Site]
 
 http://selenic.com/hg[Source code repository]
 
 http://selenic.com/mailman/listinfo/mercurial[Mailing list]
 
 COPYING
 -------
 Copyright (C) 2005 Matt Mackall.
 Free use of this software is granted under the terms of the GNU General
 Public License (GPL).