Patchwork locate: update help with replacement

login
register
mail settings
Submitter timeless@mozdev.org
Date Dec. 9, 2015, 5:29 p.m.
Message ID <98cc8438650f95b9f40d.1449682170@waste.org>
Download mbox | patch
Permalink /patch/11949/
State Deferred
Headers show

Comments

timeless@mozdev.org - Dec. 9, 2015, 5:29 p.m.
# HG changeset patch
# User timeless <timeless@mozdev.org>
# Date 1449682015 0
#      Wed Dec 09 17:26:55 2015 +0000
# Node ID 98cc8438650f95b9f40d7e8659f6d4e8c254cd14
# Parent  42aa0e570eaa364a622bc4443b0bcb79b1100a58
locate: update help with replacement
Danek Duvall - Dec. 9, 2015, 5:51 p.m.
timeless wrote:

> # HG changeset patch
> # User timeless <timeless@mozdev.org>
> # Date 1449682015 0
> #      Wed Dec 09 17:26:55 2015 +0000
> # Node ID 98cc8438650f95b9f40d7e8659f6d4e8c254cd14
> # Parent  42aa0e570eaa364a622bc4443b0bcb79b1100a58
> locate: update help with replacement
> 
> diff --git a/mercurial/commands.py b/mercurial/commands.py
> --- a/mercurial/commands.py
> +++ b/mercurial/commands.py
> @@ -4866,22 +4866,12 @@
>  def locate(ui, repo, *pats, **opts):
>      """locate files matching specific patterns (DEPRECATED)
>  
> -    Print files under Mercurial control in the working directory whose
> -    names match the given patterns.
> -
> -    By default, this command searches all directories in the working
> -    directory. To search just the current directory and its
> -    subdirectories, use "--include .".
> -
> -    If no patterns are given to match, this command prints the names
> -    of all files under Mercurial control in the working directory.
> -
> -    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 whitespace as multiple filenames.
> -
> -    See :hg:`help files` for a more versatile command.
> +    Please use `hg files` instead::
> +
> +        hg locate => hg files
> +        hg locate -f => hg files --template `hg root`"/{abspath}\\n"
> +
> +    See :hg:`help files`.

That first one isn't quite right, though.  "hg files" looks only in the
current directory by default, rather than giving you all matching files
(with relative paths), and it also explicitly requires "glob:**" when
running from the root of the working directory.

And where is {abspath} documented?

Thanks,
Danek
timeless - Dec. 9, 2015, 7:30 p.m.
We were talking about {abspath} and friends on irc..

The short answer is that none of these things are documented, which
means I can't really publish this changeset.

My goal is for people to be able to discover how to do these things.
But the path is sort of like:

Use `hg {command} -Tjson` to get a list of magical things
That tells you about {abspath}, then:
Write `hg help {deprecated-command}`

Except, -Tjson isn't ready for primetime (because once it's published,
we can't change the names of things...), so, I can't publish a patch
for `hg help templates` that explains one could use it to find these
things out.

Also, I'm partially trying to shake things out of the woodwork, as in
your point about the glob:**. -- So thanks for identifying that.

The "plan" for -Tjson and such is:
https://www.mercurial-scm.org/wiki/GenericTemplatingPlan#Steps
We probably need to write a dictionary of "how to publish a given kind
of thing using the templater", an example of something inconsistently
used is {node} (from log?) v. {hash} (from manifest?). That stuff
should probably be in a section on that page, but I don't have time to
do that today.

I don't have a published plan for the work I'm doing.

But basically, I'm trying to:
1. make it so that if a command is deprecated, there's a good
transition explanation in its help.
2. make it so that I could have figured out how to write 1 (i.e. that
hg help templates walks me through this)
3. make it so that I can easily find commands that are in funny states
(see various other patches to help that I'm sending -- specifically
the "help: fix help -c..." series).

On Wed, Dec 9, 2015 at 12:51 PM, Danek Duvall <danek.duvall@oracle.com> wrote:
> timeless wrote:
>
>> # HG changeset patch
>> # User timeless <timeless@mozdev.org>
>> # Date 1449682015 0
>> #      Wed Dec 09 17:26:55 2015 +0000
>> # Node ID 98cc8438650f95b9f40d7e8659f6d4e8c254cd14
>> # Parent  42aa0e570eaa364a622bc4443b0bcb79b1100a58
>> locate: update help with replacement
>>
>> diff --git a/mercurial/commands.py b/mercurial/commands.py
>> --- a/mercurial/commands.py
>> +++ b/mercurial/commands.py
>> @@ -4866,22 +4866,12 @@
>>  def locate(ui, repo, *pats, **opts):
>>      """locate files matching specific patterns (DEPRECATED)
>>
>> -    Print files under Mercurial control in the working directory whose
>> -    names match the given patterns.
>> -
>> -    By default, this command searches all directories in the working
>> -    directory. To search just the current directory and its
>> -    subdirectories, use "--include .".
>> -
>> -    If no patterns are given to match, this command prints the names
>> -    of all files under Mercurial control in the working directory.
>> -
>> -    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 whitespace as multiple filenames.
>> -
>> -    See :hg:`help files` for a more versatile command.
>> +    Please use `hg files` instead::
>> +
>> +        hg locate => hg files
>> +        hg locate -f => hg files --template `hg root`"/{abspath}\\n"
>> +
>> +    See :hg:`help files`.
>
> That first one isn't quite right, though.  "hg files" looks only in the
> current directory by default, rather than giving you all matching files
> (with relative paths), and it also explicitly requires "glob:**" when
> running from the root of the working directory.
>
> And where is {abspath} documented?
>
> Thanks,
> Danek
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel@selenic.com
> https://selenic.com/mailman/listinfo/mercurial-devel

Patch

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -4866,22 +4866,12 @@ 
 def locate(ui, repo, *pats, **opts):
     """locate files matching specific patterns (DEPRECATED)
 
-    Print files under Mercurial control in the working directory whose
-    names match the given patterns.
-
-    By default, this command searches all directories in the working
-    directory. To search just the current directory and its
-    subdirectories, use "--include .".
-
-    If no patterns are given to match, this command prints the names
-    of all files under Mercurial control in the working directory.
-
-    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 whitespace as multiple filenames.
-
-    See :hg:`help files` for a more versatile command.
+    Please use `hg files` instead::
+
+        hg locate => hg files
+        hg locate -f => hg files --template `hg root`"/{abspath}\\n"
+
+    See :hg:`help files`.
 
     Returns 0 if a match is found, 1 otherwise.
     """