Bug 1533157 - [fuzzy] Document how to use -q/--query with various shells, DONTBUILD, r=jgraham
authorAndrew Halberstadt <ahalberstadt@mozilla.com>
Thu, 07 Mar 2019 10:05:21 +0000
changeset 520745 c96eda70661bf116ba9afefcb40e70c974fbc7cb
parent 520744 12e0e7785e853ea9ec95d579afdbc05487d84d37
child 520746 975644295f21a5bd55d551abd09109a2b7d771eb
push id10862
push userffxbld-merge
push dateMon, 11 Mar 2019 13:01:11 +0000
treeherdermozilla-beta@a2e7f5c935da [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjgraham
bugs1533157
milestone67.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1533157 - [fuzzy] Document how to use -q/--query with various shells, DONTBUILD, r=jgraham Differential Revision: https://phabricator.services.mozilla.com/D22388
tools/tryselect/docs/selectors/fuzzy.rst
--- a/tools/tryselect/docs/selectors/fuzzy.rst
+++ b/tools/tryselect/docs/selectors/fuzzy.rst
@@ -98,16 +98,74 @@ If instead you want the intersection of 
 
 Using query intersections is especially useful with presets:
 
 .. code-block:: shell
 
     # selects all windows perf tasks
     $ mach try fuzzy --preset perf -xq "windows"
 
+
+Shell Conflicts
+~~~~~~~~~~~~~~~
+
+Unfortunately ``fzf``'s query language uses some characters (namely ``'``, ``!`` and ``$``) that can
+interfere with your shell when using ``-q/--query``. Below are some tips for how to type out a query
+on the command line.
+
+The ``!`` character is typically used for history expansion. If you don't use this feature, the
+easiest way to specify queries on the command line is to disable it:
+
+.. code-block:: shell
+
+    # bash
+    $ set +H
+    $ ./mach try fuzzy -q "'foo !bar"
+
+    # zsh
+    $ setopt no_banghist
+    $ ./mach try fuzzy -q "'foo !bar"
+
+If using ``bash``, add ``set +H`` to your ``~/.bashrc``, ``~/.bash_profile`` or equivalent. If using
+``zsh``, add ``setopt no_banghist`` to your ``~/.zshrc`` or equivalent.
+
+If you don't want to disable history expansion, you can escape your queries like this:
+
+.. code-block:: shell
+
+    # bash
+    $ ./mach try fuzzy -q $'\'foo !bar'
+
+    # zsh
+    $ ./mach try fuzzy -q "'foo \!bar"
+
+
+The third option is to use ``-e/--exact`` which reverses the behaviour of the ``'`` character (see
+:ref:`additional-arguments` for more details). Using this flag means you won't need to escape the
+``'`` character as often and allows you to run your queries like this:
+
+.. code-block:: shell
+
+    # bash and zsh
+    $ ./mach try fuzzy -eq 'foo !bar'
+
+This method is only useful if you find you almost always prefix terms with ``'`` (and rarely use
+fuzzy terms). Otherwise as soon as you want to use a fuzzy match you'll run into the same problem as
+before.
+
+.. note:: All the examples in these three approaches will select the same set of tasks.
+
+If you use ``fish`` shell, you won't need to escape ``!``, however you will need to escape ``$``:
+
+.. code-block:: shell
+
+    # fish
+    $ ./mach try fuzzy -q "'foo !bar baz\$"
+
+
 Test Paths
 ----------
 
 One or more paths to a file or directory may be specified as positional arguments. When
 specifying paths, the list of available tasks to choose from is filtered down such that
 only suites that have tests in a specified path can be selected. Notably, only the first
 chunk of each suite/platform appears. When the tasks are scheduled, only tests that live
 under one of the specified paths will be run.
@@ -116,17 +174,17 @@ under one of the specified paths will be
 
     When using paths, be aware that all tests under the specified paths will run in the
     same chunk. This might produce a different ordering from what gets run on production
     branches, and may yield different results.
 
     For suites that restart the browser between each manifest (like mochitest), this
     shouldn't be as big of a concern.
 
-Paths can be used with the interactive fzf window, or using the ``-q/--query`` argument.
+Paths can be used with the interactive ``fzf`` window, or using the ``-q/--query`` argument.
 For example, running:
 
 .. code-block:: shell
 
     $ mach try fuzzy layout/reftests/reftest-sanity -q "!pgo !cov !asan 'linux64"
 
 Would produce the following ``try_task_config.json``:
 
@@ -146,33 +204,36 @@ Would produce the following ``try_task_c
         "test-linux64/opt-reftest-e10s-1",
         "test-linux64/opt-reftest-no-accel-e10s-1",
       ]
     }
 
 Inside of these tasks, the reftest harness will only run tests that live under
 ``layout/reftests/reftest-sanity``.
 
+
+.. _additional-arguments:
+
 Additional Arguments
 --------------------
 
 There are a few additional command line arguments you may wish to use:
 
 ``-e/--exact``
-By default, fzf treats terms as a fuzzy match and prefixing a term with ``'`` turns it into an exact
+By default, ``fzf`` treats terms as a fuzzy match and prefixing a term with ``'`` turns it into an exact
 match. If passing in ``--exact``, this behaviour is reversed. Non-prefixed terms become exact, and a
 ``'`` prefix makes a term fuzzy.
 
 ``--full``
 By default, only target tasks (e.g tasks that would normally run on mozilla-central)
 are generated. Passing in ``--full`` allows you to select from all tasks. This is useful for
 things like nightly or release tasks.
 
 ``-u/--update``
-Update the bootstrapped fzf binary to the latest version.
+Update the bootstrapped ``fzf`` binary to the latest version.
 
 For a full list of command line arguments, run:
 
 .. code-block:: shell
 
     $ mach try fuzzy --help
 
 For more information on using ``fzf``, run: