support combining -c and -e
previously -k was misdocumented:
* the first line didn't mention it
* the help half implied you could do help -k keyword topic
with these changes, -k just changes the search method
support -c and -e for -k searches
There are two non-interactive internal merge tools, :other and :local,
but they don't really merge, they just pick all changes from the local
or other version of the file. In some situations, it is known that we
want a merge and also know that all merge conflicts should be resolved
in one direction. Although external merge tools can do this, sometimes
it can be convenient to do so from within hg, without invoking a merge
tool. These new :merge-local and :merge-other tools can do just that.
test for "hg help -c config" in help config
``section``
-----------
section text
``def1``
definition of def1
$ hg help scope.def1
should list this paragraph, but not section text below...
section text
``def2``
definition of def2
$ hg help scope.def2
should list this paragraph, but not section text below...
section text
$ hg help scope.section should show everything from the first
section text to this last line.
``section2``
------------
'union merge' is a merge strategy which adds both left and right hand side
of a conflict region. Git implements this merge strategy which is very
practical to have for merging e.g. the Changelog file.
There are a lot of non-human consumers of Mercurial. And the challenges
and considerations for machines consuming Mercurial is significantly
different from what humans face.
I think there are enough special considerations around how machines
consume Mercurial that a dedicated help topic is warranted. I concede
the audience for this topic is probably small compared to the general
audience. However, lots of normal Mercurial users do things like create
one-off shell scripts for common workflows that I think this is useful
enough to be in the install (as opposed to, say, a wiki page - which
most users will likely never find).
This text is by no means perfect. But you have to start somewhere. I
think I did cover the important parts, though.
Currently, there is no way to recover from a missing or corrupt fncache
file in place (a clone is required). For certain use cases such as
servers and with large repositories, an in-place repair may be
desirable. This patch adds functionality for in-place repair of the
fncache.
The `hg debugrebuildfncache` command is introduced. It ensures the
fncache is up to date by reconstructing the fncache from all seen files
encountered during a brute force traversal of the repository's entire
history.
The command will add missing entries and will prune excess ones.
Currently, the command no-ops unless the repository has the fncache
requirement. The command could later grow the ability to "upgrade" an
existing repository to be fncache enabled, if desired.
When testing this patch on a local clone of the Firefox repository, it
removed a bunch of entries. Investigation revealed that removed entries
belonged to empty (0 byte size) .i filelogs. The functionality for
pruning fncache of stripped revlogs was introduced in 93ba76bfbe8a, so
the presence of these entries likely predates this feature.
$TESTDIR is added to the path, so this is superfluous. Also,
inconsistent use of quotes means we might have broken on tests with
paths containing spaces.
"working directory" is the standard term, we should use it consistently.
But I didn't touch the hint, "run 'hg update' to get a working copy", because
"get a working directory" sounds a bit odd.
The censor command is a core extension which can replace the contents of a
historical file revision with a censor "tombstone" which can be exchanged
with older clients in place of the real revision data. The command rewrites
the filelog by copying revision-by-revision.
Care must be taken to expand the fulltext of the children of the censored
revision before copying them to the new filelog; they might be stored as
deltas against the uncensored revision, and those deltas will be invalidated.
For more background on the censorship feature design, see:
http://mercurial.selenic.com/wiki/CensorPlan
Now that we have decided on the use of 'name' instead of 'label' we rename this
function accordingly.
The old method 'debuglabelcomplete' has been left as a deprecated command so
that current scripts don't break.
Like 'forget', git and svn subrepos are currently not supported. Unfortunately
the name 'remove' is already used in the subrepo classes, so we break the
convention of naming the subrepo function after the command.
See previous patch descriptions for the motivation.
The tests reflect the current state of the world -- as we add support we'll see
changes in the test output.
Used to be that `hg help hgrc.paths` would show
"paths"
-------
Assigns symbolic names to repositories. The left side is the symbolic
name, and the right gives the directory or URL that is the location of the
repository. Default paths can be declared by setting the following
entries.
and stop there. Obviously the result seems better as shown in the
attached test.
We used to have two slightly different message which people wouldn't read...
and then complain that they couldn't find the global options or examples.
So we unify them into one message that's upfront that STUFF IS
INTENTIONALLY HIDDEN and that looks more like our normal hint style.
Old behavior:
hg help x hg x -h hg help -e x hg help -c x
config topic topic (!) - cmd
showconfig cmd topic (!) - cmd
rebase cmd cmd ext cmd
New behavior:
hg help x hg x -h hg help -e x hg help -c x
config topic cmd - cmd
showconfig cmd cmd - cmd
rebase cmd cmd ext cmd
When `hg help foobar` fails, it now suggests using `hg help --keyword foobar`
instead of printing a full page of basic commands.
This should greatly increases discoverability of the `hg help --keyword`
argument.
Before this changeset, when no topic were matching the provided keyword ( in
command such as `hg help --keyword babar`) the output was empty. This is
confusing and unhelpful for new users seeking assistance in the help.
We now display:
$ hg help --keyword babar
abort: no matches
(try "hg help" for a list of topics)
This send users in a new direction where they may find what they are looking for.
When using a different language than English, deprecated options were only
removed from the output of `hg help anycmd` when "DEPRECATED" in the options
description was translated.
When table data contained a newline, the result of minirst.maketable
did not look nice plus it was not recognised by minirst.format:
== === ====
l1 1 one
l2 2 2
22
l3
== === ====
This problem occurred when the description of options had a very long
translation which was split by newlines. Do not bother a translator with
this detail.
The multiline translations for option descriptions have been fixed in
7a88a81d5d9e in it.po, de.po and ro.po. I manually did the same as this patch
does, I removed the newlines.
When a newline was in the description, this created unusable help output:
$ hg help somecommand
hg somecommand [option]...
with somecommand, you can...
options:
== =================== =======================================================
=================================== --longdesc VALUE xxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -n --norm
normal desc --newline VALUE line1 line2 == =================== ===============
===========================================================================
now this looks much nicer:
...
options:
--longdesc VALUE xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-n --norm normal desc
--newline VALUE line1 line2
This extension has always had correctness issues and has been
unmaintained for years. It is now removed in favor of the third-party
hgwatchman which is maintained and appears to be correct.
Users with inotify enabled in their config files will fall back to
standard status performance.
Was the behavior correct and the description wrong so it should be updated as
in this patch? Or should the code work as the documentation says?
Both ways could make some sense ... but none of them are obvious in all cases.
One place where it currently cause problems is when the current revision has
another branch head that is closer to tip but closed. 'hg rebase' refuses to
rebase to that as it only see the tip-most unclosed branch head which is the
current revision.
/me kind of likes named branches, but no so much how branch closing works ...
Before this patch, "hg help -k KEYWORD" fails, if there is the
extension of which name includes ".", because "extensions.load()"
invoked from "help.topicmatch()" fails to look such extension up, even
though it is already loaded in.
"help.topicmatch()" invokes "extensions.load()" with the name gotten
from "extensions.enabled()". The former expects full name of extension
(= key in '[extensions]' section), but the latter returns names
shortened by "split('.')[-1]". This difference causes failure of
looking extension up.
This patch adds "shortname" argument to "extensions.enabled()" to make
it return shortened names only if it is True. "help.topicmatch()"
turns it off to get full name of extensions.
Then, this patch shortens full name of extensions by "split('.')[-1]"
for showing them in the list of extensions.
Shortening is also applied on names gotten from
"extensions.disabled()" but harmless, because it returns only
extensions directly under "hgext" and their names should not include
".".
The old docs emphasized topological heads rather than branch heads and
incorrectly defined branch heads as not having children rather than
descendants.
The dispatch code now enables filtering of "hidden" changesets globally. The
filter is installed before command and extension invocation. The `--hidden`
switch is now global and disables this filtering for any command.
Code in log dedicated to changeset exclusion is removed as this global filtering
has the same effect.
Before this patch, there is no information about whether help document
is fully displayed or not.
So, some users seem to misunderstand "-v" for "hg help" just as "the
option to show list of global options": experience on "hg help -v" for
some commands not containing verbose containers may strengthen this
misunderstanding.
Such users have less opportunity for noticing omitted help document,
and this may cause insufficient understanding about Mercurial.
This patch indicates help omitting, if help document is not fully
displayed.
For command help, the message below is displayed at the end of help
output, if help document is not fully displayed:
use "hg -v help xxxx" to show more complete help and the global
options
and otherwise:
use "hg -v help xxxx" to show the global options
For topics and extensions help, the message below is displayed, only
if help document is not fully displayed:
use "hg help -v xxxx" to show more complete help
This allows users to know whether there is any omitted information or
not exactly, and can trigger "hg help -v" invocation.
This patch causes formatting help document twice, to switch messages
one for omitted help, and another for not omitted. This decreases
performance of help document formatting, but it is not mainly focused
at help command invocation, so this wouldn't become problem.
Before this patch, there is no information about what users should (or
can) do for recovery from corruption of repositories.
This patch adds URL of the Mercurial Wiki page explaining about
recovery from corruption.
This patch adds "doc/check-seclevel.py" which checks below in help
documents:
- whether unknown or unavailable section marks are used or not
- whether appropriate section mark is used at sub-sectioning
It should be invoked in "doc" directory.
It checks all help documents of Mercurial (topics, commands,
extensions), if no file is specified by --file option.
With --file option, it checks contents of the specified file as help
document, for self testing purpose: -t/-c/-e/-C are used to specify
what kind of help document contents of the specified file is.
This checking is related to changeset 8d980034517b.
This makes the 'additional help topics' list consistent with the output from
keyword search (for instance subrepo/subrepos).
The sorting by longest name was introduced in 4cbe49492ad3. There might have
been a good reason for it back then, but now it seems like a better idea to
place the preferred name first in the list in helptable.
This patch fixes the synopsis shown for extension commands in keyword search
results. A previous patch erroneously caused the extension synopsis to be shown
instead.
Test cases for keyword search are missing, so I added a one.
This patch changes the function which generates help text about commands and
options to use RST formatting. Tables describing options have been formatted
using RST table markup for some time already, so their appearance does not
change. Command lists, however, change appearance.
To format non-verbose command lists, RST field list markup was chosen, because
it resembles the old format:
<http://docutils.sourceforge.net/docs/user/rst/quickref.html#field-lists>
In the old (hand-coded) format of non-verbose command lists, the left column is
12 characters wide. Our minirst implementation formats field lists with a left
column 14 characters wide, so this patch changes the appearance of help output
correspondingly:
<http://markmail.org/message/krl4cxopsnii7s6z?q=mercurial+reinert+from:%22Olav+Reinert%22&page=2>
The minirst markup most closely resembling the old verbose command lists is
definition lists. But using it would cause a blank line to be inserted between
each command definition, making the output excessively long, and no more
useful than before. To avoid this, I chose to use field lists also for verbose
command help, resulting in output like this example:
add add the specified files on the next commit
annotate, blame
show changeset information by line for each file
clone make a copy of an existing repository
commit, ci commit the specified files or all outstanding changes
diff diff repository (or selected files)
export dump the header and diffs for one or more changesets
forget forget the specified files on the next commit
init create a new repository in the given directory
log, history show revision history of entire repository or files
merge merge working directory with another revision
phase set or show the current phase name
pull pull changes from the specified source
push push changes to the specified destination
qdiff diff of the current patch and subsequent modifications
qinit init a new queue repository (DEPRECATED)
qnew create a new patch
qpop pop the current patch off the stack
qpush push the next patch onto the stack
qrefresh update the current patch
remove, rm remove the specified files on the next commit
serve start stand-alone webserver
status, st show changed files in the working directory
summary, sum summarize working directory state
update, up, checkout, co
update working directory (or switch revisions)
This change is a move towards generating all help text as a list of strings
marked up with RST.
The output of "hg help" is changed to ensure that the column containing
descriptions of commands, extensions, and other topics is correctly alignmened.
The default width of field lists is changed from 12 to 14 to align minirst with
the rst2html tool. Shrinking the width of the left column to fit the content is
removed, to keep formatting simple and uniform.
Before, the help text said that Mercurial would assume 'yes' for all
prompts, but this is confusing since many prompts don't have any 'yes'
choice. It now more accurately describes what will happen.
New users have a tendency to mistake 'revert' as the command to use to
check out old revisions. They also occasionally mistake revert for a
generalized undo (compare rollback).
This version intentionally aims to avoid mentioning 'earlier' and thus
intentionally no longer alludes to the (secondary) -r behavior (which
in fact is not actually limited to 'earlier').
Instead, we mention checkout state, to convey that we can
restore things to the way they were when checked out.
Example
$ hg clone --jump foo bar
hg clone: option --jump not recognized
hg clone [OPTION]... SOURCE [DEST]
make a copy of an existing repository
options:
-U --noupdate the clone will include an empty working copy (only a
repository)
-u --updaterev REV revision, tag or branch to check out
-r --rev REV [+] include the specified changeset
-b --branch BRANCH [+] clone only the specified branch
--pull use pull protocol to copy metadata
--uncompressed use uncompressed transfer (fast over LAN)
-e --ssh CMD specify ssh command to use
--remotecmd CMD specify hg command to run on the remote side
--insecure do not verify server certificate (ignoring
web.cacerts config)
[+] marked option can be specified multiple times
use "hg help clone" to show the full help text
Motivation for this change
If the user already has specified the command, he probably already knows
the command to some extent. Apparently, he has a problem with the options,
so we show him just the synopsis with the short help and the details about
the options, with a hint on the last line how to get the full help text.
Why is Mercurial better with this change?
Experts who just forgot about the details of an option don't get that
much text thrown at them, while the newbies still get a hint on the last
line how to get the full help text.
This adds a " (glob)" marker that works like a simpler version of
(re): "*" is converted to ".*", and "?" is converted to ".".
Both special characters can be escaped using "\", and the backslash
itself can be escaped as well.
Other glob-style syntax, like "**", "[chars]", or "[!chars]", isn't
supported.
Consider this test:
$ hg glog --template '{rev}:{node|short} "{desc}"\n'
@ 2:20c4f79fd7ac "3"
|
| o 1:38f24201dcab "2"
|/
o 0:2a18120dc1c9 "1"
Because each line beginning with "|" can be compiled as a regular
expression (equivalent to ".*|"), they will match any output.
Similarly:
$ echo foo
The blank output line can be compiled as a regular expression and will
also match any output.
With this patch, none of the above output lines will be matched as
regular expressions. A line must end in " (re)" in order to be matched
as one.
Lines are still matched literally first, so the following will pass:
$ echo 'foo (re)'
foo (re)