Please review.
Benoit
# HG changeset patch
# User Benoit Boissinot <benoit.boissinot@ens-lyon.org>
# Node ID 5d9d3a1be78c733cb3e7cbeadbd0301ff4437ef0
# Parent 4b3be0f5925fec4958d4129543de9e6d3c91db4c
generate hg.1.txt from the docstrings
diff -r 4b3be0f5925f -r 5d9d3a1be78c doc/Makefile
--- a/doc/Makefile Tue Nov 1 20:46:43 2005 +0200
+++ b/doc/Makefile Wed Nov 2 12:23:00 2005 +0200
@@ -7,6 +7,12 @@
man: $(MAN)
html: $(HTML)
+
+hg.1.txt: hg.gendoc.1.txt
+ touch hg.1.txt
+
+hg.gendoc.1.txt:
+ python gendoc.py > $@
%: %.xml
xmlto man $*.xml
diff -r 4b3be0f5925f -r 5d9d3a1be78c doc/hg.1.txt
--- a/doc/hg.1.txt Tue Nov 1 20:46:43 2005 +0200
+++ b/doc/hg.1.txt Wed Nov 2 12:23:00 2005 +0200
@@ -13,42 +13,6 @@
DESCRIPTION
-----------
The hg(1) command provides a command line interface to the Mercurial system.
-
-OPTIONS
--------
-
--R, --repository::
- repository root directory
-
---cwd::
- change working directory
-
--y, --noninteractive::
- do not prompt, assume 'yes' for any required answers
-
--q, --quiet::
- suppress output
-
--v, --verbose::
- enable additional output
-
---debug::
- enable debugging output
-
---traceback::
- print traceback on exception
-
---time::
- time how long the command takes
-
---profile::
- print command execution profile
-
---version::
- output version information and exit
-
--h, --help::
- display help and exit
COMMAND ELEMENTS
----------------
@@ -70,564 +34,7 @@
fast and the old-http:// protocol which is much slower but does not
require a special server on the web host.
-COMMANDS
---------
-
-add [options] [files ...]::
- Schedule files to be version controlled and added to the repository.
-
- The files will be added to the repository at the next commit.
-
- If no names are given, add all files in the current directory and
- its subdirectories.
-
-addremove [options] [files ...]::
- 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.
-
- Without the -a option, annotate will avoid processing files it
- detects as binary. With -a, annotate will generate an annotation
- anyway, probably with undesirable results.
-
- options:
- -a, --text treat all files as text
- -I, --include <pat> include names matching the given patterns
- -X, --exclude <pat> exclude names matching the given patterns
- -r, --revision <rev> annotate the specified revision
- -u, --user list the author
- -c, --changeset list the changeset
- -n, --number list the revision number (default)
-
-bundle <file> <other>::
- (EXPERIMENTAL)
-
- Generate a compressed changegroup file collecting all changesets
- not found in the other repository.
-
- This file can then be transferred using conventional means and
- applied to another repository with the unbundle command. This is
- useful when native push and pull are not available or when
- exporting an entire repository is undesirable. The standard file
- extension is ".hg".
-
- Unlike import/export, this exactly preserves all changeset
- contents including permissions, rename data, and revision history.
-
-cat [options] <file ...>::
- Print the specified files as they were at the given revision.
- If no revision is given then the tip is used.
-
- Output may be to a file, in which case the name of the file is
- given using a format string. The formatting rules are the same as
- for the export command, with the following additions:
-
- %s basename of file being printed
- %d dirname of file being printed, or '.' if in repo root
- %p root-relative path name of file being printed
-
- options:
- -I, --include <pat> include names matching the given patterns
- -X, --exclude <pat> exclude names matching the given patterns
- -o, --output <filespec> print output to file with formatted name
- -r, --rev <rev> print the given revision
-
-clone [options] <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 location of the source is added to the new repository's
- .hg/hgrc file, as the default to be used for future pulls.
-
- For efficiency, hardlinks are used for cloning whenever the source
- and destination are on the same filesystem. Some filesystems,
- such as AFS, implement hardlinking incorrectly, but do not report
- errors. In these cases, use the --pull option to avoid
- hardlinking.
-
- options:
- -U, --noupdate do not update the new working directory
- --pull use pull protocol to copy metadata
- -e, --ssh specify ssh command to use
- --remotecmd specify hg command to run on the remote side
-
-commit [options] [files...]::
- Commit changes to the given files into the repository.
-
- If a list of files is omitted, all changes reported by "hg status"
- from the root of the repository 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
- -I, --include <pat> include names matching the given patterns
- -X, --exclude <pat> exclude names matching the given patterns
- -m, --message <text> use <text> as commit message
- -l, --logfile <file> read the commit message from <file>
- -d, --date <datecode> record datecode as commit date
- -u, --user <user> record user as commiter
-
- aliases: ci
-
-copy <source ...> <dest>::
- Mark dest as having copies of source files. If dest is a
- directory, copies are put in that directory. If dest is a file,
- there can only be one source.
-
- By default, this command copies the contents of files as they
- stand in the working directory. If invoked with --after, the
- operation is recorded, but no copying is performed.
-
- This command takes effect in the next commit.
-
- NOTE: This command should be treated as experimental. While it
- should properly record copied files, this information is not yet
- fully used by merge, nor fully reported by log.
-
- Options:
- -A, --after record a copy that has already occurred
- -I, --include <pat> include names matching the given patterns
- -X, --exclude <pat> exclude names matching the given patterns
- -f, --force forcibly copy over an existing managed file
-
- aliases: cp
-
-diff [-a] [-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.
-
- Without the -a option, diff will avoid generating diffs of files
- it detects as binary. With -a, diff will generate a diff anyway,
- probably with undesirable results.
-
- options:
- -a, --text treat all files as text
- -I, --include <pat> include names matching the given patterns
- -X, --exclude <pat> exclude names matching the given patterns
-
-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
-
- Without the -a option, export will avoid generating diffs of files
- it detects as binary. With -a, export will generate a diff anyway,
- probably with undesirable results.
-
- options:
- -a, --text treat all files as text
- -o, --output <filespec> print output to file with formatted name
-
-forget [options] [files]::
- Undo an 'hg add' scheduled for the next commit.
-
- options:
- -I, --include <pat> include names matching the given patterns
- -X, --exclude <pat> exclude names matching the given patterns
-
-grep [options] pattern [files]::
- Search revisions of files for a regular expression.
-
- This command behaves differently than Unix grep. It only accepts
- Python/Perl regexps. It searches repository history, not the
- working directory. It always prints the revision number in which
- a match appears.
-
- By default, grep only prints output for the first revision of a
- file in which it finds a match. To get it to print every revision
- that contains a change in match status ("-" for a match that
- becomes a non-match, or "+" for a non-match that becomes a match),
- use the --all flag.
-
- options:
- -0, --print0 end fields with NUL
- -I, --include <pat> include names matching the given patterns
- -X, --exclude <pat> exclude names matching the given patterns
- --all print all revisions that match
- -i, --ignore-case ignore case when matching
- -l, --files-with-matches print only filenames and revs that match
- -n, --line-number print matching line numbers
- -r <rev>, --rev <rev> search in given revision range
- -u, --user print user who committed change
-
-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> -f] <patches>::
- Import a list of patches and commit them individually.
-
- If there are outstanding changes in the working directory, import
- will abort unless given the -f flag.
-
- If a patch looks like a mail message (its first line starts with
- "From " or looks like an RFC822 header), it will not be applied
- unless the -f option is used. The importer neither parses nor
- discards mail headers, so use -f only to override the "mailness"
- safety check, not to import a real mail message.
-
- options:
- -p, --strip <n> directory strip option for patch. This has the same
- meaning as the corresponding patch option
- -b <path> base directory to read patches from
- -f, --force skip check for outstanding uncommitted changes
-
- aliases: patch
-
-incoming [-p] [source]::
- Show new changesets found in the specified repo or the default
- pull repo. These are the changesets that would be pulled if a pull
- was requested.
-
- Currently only local repositories are supported.
-
- options:
- -p, --patch show patch
-
- aliases: in
-
-init [dest]::
- Initialize a new repository in the given directory. If the given
- directory does not exist, it is created.
-
- If no directory is given, the current directory is used.
-
-locate [options] [files]::
- Print all files under Mercurial control whose names match the
- given patterns.
-
- 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 filenames.
-
- options:
-
- -0, --print0 end filenames with NUL, for use with xargs
- -f, --fullpath print complete paths from the filesystem root
- -I, --include <pat> include names matching the given patterns
- -r, --rev <rev> search the repository as it stood at rev
- -X, --exclude <pat> exclude names matching the given patterns
-
-log [-r revision ...] [-p] [files]::
- Print the revision history of the specified files 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:
- -I, --include <pat> include names matching the given patterns
- -X, --exclude <pat> exclude names matching the given patterns
- -r, --rev <A> show the specified revision or range
- -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.
-
-outgoing [-p] [dest]::
- Show changesets not found in the specified destination repo or the
- default push repo. These are the changesets that would be pushed
- if a push was requested.
-
- options:
- -p, --patch show patch
-
- aliases: out
-
-parents::
- Print the working directory's parent revisions.
-
-paths [NAME]::
- Show definition of symbolic path name NAME. If no name is given, show
- definition of available names.
-
- Path names are defined in the [paths] section of /etc/mercurial/hgrc
- and $HOME/.hgrc. If run inside a repository, .hg/hgrc is used, too.
-
-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.
-
- Valid URLs are of the form:
-
- local/filesystem/path
- http://[user@]host[:port][/path]
- https://[user@]host[:port][/path]
- ssh://[user@]host[:port][/path]
-
- SSH requires an accessible shell account on the destination machine
- and a copy of hg in the remote path. With SSH, paths are relative
- to the remote user's home directory by default; use two slashes at
- the start of a path to specify it as relative to the filesystem root.
-
- options:
- -u, --update update the working directory to tip after pull
- -e, --ssh specify ssh command to use
- --remotecmd specify hg command to run on the remote side
-
-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.
-
- By default, push will refuse to run if it detects the result would
- increase the number of remote heads. This generally indicates the
- the client has forgotten to sync and merge before pushing.
-
- Valid URLs are of the form:
-
- local/filesystem/path
- ssh://[user@]host[:port][/path]
-
- SSH requires an accessible shell account on the destination
- machine and a copy of hg in the remote path.
-
- options:
-
- -f, --force force update
- -e, --ssh specify ssh command to use
- --remotecmd specify hg command to run on the remote side
-
-rawcommit [-p -d -u -F -m -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 [options] [files ...]::
- Schedule the indicated files for removal from the repository.
-
- This command schedules the files to be removed at the next commit.
- This only removes files from the current branch, not from the
- entire project history. If the files still exist in the working
- directory, they will be deleted from it.
-
- aliases: rm
-
-rename <source ...> <dest>::
- Mark dest as copies of sources; mark sources for deletion. If
- dest is a directory, copies are put in that directory. If dest is
- a file, there can only be one source.
-
- By default, this command copies the contents of files as they
- stand in the working directory. If invoked with --after, the
- operation is recorded, but no copying is performed.
-
- This command takes effect in the next commit.
-
- NOTE: This command should be treated as experimental. While it
- should properly record rename files, this information is not yet
- fully used by merge, nor fully reported by log.
-
- Options:
- -A, --after record a rename that has already occurred
- -f, --force forcibly copy over an existing managed file
-
- aliases: mv
-
-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
- -6, --ipv6 use IPv6 in addition to IPv4
-
-status [options] [files]::
- Show changed files in the working directory. If no names are
- given, all files are shown. Otherwise, only files matching the
- given names are shown.
-
- The codes used to show the status of files are:
-
- M = changed
- A = added
- R = removed
- ? = not tracked
-
- options:
-
- -m, --modified show only modified files
- -a, --added show only added files
- -r, --removed show only removed files
- -u, --unknown show only unknown (not tracked) files
- -n, --no-status hide status prefix
- -0, --print0 end filenames with NUL, for use with xargs
- -I, --include <pat> include names matching the given patterns
- -X, --exclude <pat> exclude names matching the given patterns
-
-tag [-l -m <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
- -m, --message <text> message for tag commit log entry
- -d, --date <datecode> datecode for commit
- -u, --user <user> user for commit
-
- 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.
-
-unbundle <file>::
- (EXPERIMENTAL)
-
- Apply a compressed changegroup file generated by the bundle
- command.
-
-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.
+include::hg.gendoc.1.txt[]
FILE NAME PATTERNS
------------------
diff -r 4b3be0f5925f -r 5d9d3a1be78c doc/gendoc.py
--- /dev/null Thu Jan 1 00:00:00 1970 +0000
+++ b/doc/gendoc.py Wed Nov 2 12:23:00 2005 +0200
@@ -0,0 +1,91 @@
+from mercurial.commands import table, globalopts
+from mercurial.i18n import gettext as _
+import mercurial.version
+import sys, textwrap
+
+def get_desc(docstr):
+ if not docstr:
+ return "", ""
+ # sanitize
+ docstr = docstr.strip("\n")
+ docstr = docstr.rstrip()
+ shortdesc = docstr.splitlines()[0].strip()
+
+ i = docstr.find("\n")
+ if i != -1:
+ desc = docstr[i+2:]
+ else:
+ desc = " %s" % shortdesc
+ return (shortdesc, desc)
+
+def get_opts(opts):
+ for shortopt, longopt, default, desc in opts:
+ allopts = []
+ if shortopt:
+ allopts.append("-%s" % shortopt)
+ if longopt:
+ allopts.append("--%s" % longopt)
+ desc += default and _(" (default: %s)") % default or ""
+ yield(", ".join(allopts), desc)
+
+def get_cmd(cmd):
+ d = {}
+ attr = table[cmd]
+ cmds = cmd.lstrip("^").split("|")
+
+ d['synopsis'] = attr[2]
+ d['cmd'] = cmds[0]
+ d['aliases'] = cmd.split("|")[1:]
+ d['desc'] = get_desc(attr[0].__doc__)
+ d['opts'] = list(get_opts(attr[1]))
+ return d
+
+
+def show_doc(ui):
+ def bold(s, text=""):
+ ui.write("%s\n%s\n%s\n" % (s, "="*len(s), text))
+ def underlined(s, text=""):
+ ui.write("%s\n%s\n%s\n" % (s, "-"*len(s), text))
+
+ # print options
+ underlined(_("OPTIONS"))
+ for optstr, desc in get_opts(globalopts):
+ ui.write("%s::\n %s\n\n" % (optstr, desc))
+
+ # print cmds
+ underlined(_("COMMANDS"))
+ h = {}
+ for c, attr in table.items():
+ f = c.split("|")[0]
+ f = f.lstrip("^")
+ h[f] = c
+ cmds = h.keys()
+ cmds.sort()
+
+ for f in cmds:
+ if f.startswith("debug"): continue
+ d = get_cmd(h[f])
+ # synopsis
+ ui.write("%s::\n" % d['synopsis'].replace("hg ","", 1))
+ # description
+ ui.write("%s\n\n" % d['desc'][1])
+ # options
+ opt_output = list(d['opts'])
+ if opt_output:
+ opts_len = max([len(line[0]) for line in opt_output])
+ ui.write(_(" options:\n"))
+ for optstr, desc in opt_output:
+ if desc:
+ s = "%-*s %s" % (opts_len, optstr, desc)
+ else:
+ s = optstr
+ s = textwrap.fill(s, initial_indent=4 * " ",
+ subsequent_indent=(6 + opts_len) * " ")
+ ui.write("%s\n" % s)
+ ui.write("\n")
+ # aliases
+ if d['aliases']:
+ ui.write(_(" aliases: %s\n\n") % " ".join(d['aliases']))
+
+if __name__ == "__main__":
+ show_doc(sys.stdout)
|