diff --git a/tools/tryselect/docs/selectors/fuzzy.rst b/tools/tryselect/docs/selectors/fuzzy.rst index a12dfd462332d..0fca7eaff0d82 100644 --- a/tools/tryselect/docs/selectors/fuzzy.rst +++ b/tools/tryselect/docs/selectors/fuzzy.rst @@ -5,54 +5,157 @@ The fuzzy selector uses a tool called `fzf`_. It allows you to filter down all o from a terminal based UI and an intelligent fuzzy finding algorithm. If the ``fzf`` binary is not installed, you'll be prompted to bootstrap it on first run. + +Understanding the Interface +--------------------------- + +When you run ``mach try fuzzy`` an interface similar to the one below will open. This is `fzf`_. + +.. image:: fzf.png + +There's a lot to unpack here, so let's examine each component a bit more closely. + + A. The set of tasks that match the currently typed-out query. In the above image only tasks that + match the query ``'linux64 mochibrochr`` are displayed. + + B. The set of selected tasks. These are the tasks that will be scheduled once you hit ``Enter``. + In other words, if the task you want does not appear here, *it won't be scheduled*. + + C. Count information of the form ``x/y (z)``, where ``x`` is the number of tasks that match the + current query, ``y`` is the total number of tasks and ``z`` is the number of tasks you have + selected. + + D. The input bar for entering queries. As you type you'll notice the list of tasks in ``A`` + starts to update immediately. In the image above, the query ``'linux64 mochibrochr`` is entered. + Correspondingly only tasks matching that query are displayed. + +In general terms, you first find tasks on the left. Then you move them over to the right by +selecting them. Once you are satisfied with your selection, press ``Enter`` to push to try. + + Selecting Tasks --------------- -Running ``mach try fuzzy`` without arguments will open up the ``fzf`` interface with all of the -available tasks pre-populated on the left. If you start typing, you'll notice tasks are instantly -filtered with a fuzzy match. You can select tasks by ``Ctrl+Click`` with the mouse or by using the -following keyboard shortcuts: +There are few ways you can select tasks. If you are feeling a bit overwhelmed, it might be best to +stick with the mouse to start: + + 1. Enter a query (e.g ``mochitest``) to reduce the task list a little. + 2. Scroll up and look for the task(s) you want. + 3. ``Right-Click`` as many tasks as desired to select them. + 4. Optionally delete your query, go back to step 1) and repeat. + 5. Press ``Enter`` to push (or ``Esc`` to cancel). + +.. note:: + + Dependencies are automatically filled in, so you can select a test task without needing + to select the build it depends on. + +As you ``Right-Click``, notice that a little arrow appears to the left of the task label. This +indicates that the task is selected and exists in the preview pane to the right. + +Once you are a bit more comfortable with the interface, using the keyboard is much better at quickly +selecting tasks. Here are the main shortcuts you'll need: .. code-block:: text - Ctrl-K / Down => Move cursor up - Ctrl-J / Up => Move cursor down + Ctrl-K / Up => Move cursor up + Ctrl-J / Down => Move cursor down Tab => Select task + move cursor down Shift-Tab => Select task + move cursor up Ctrl-A => Select all currently filtered tasks Ctrl-D => De-select all currently filtered tasks Ctrl-T => Toggle select all currently filtered tasks - Alt-Bspace => Clear input + Alt-Bspace => Clear query from input bar + Enter => Accept selection and exit + Ctrl-C / Esc => Cancel selection and exit ? => Toggle preview pane -Notice you can type a query, select some tasks, clear the query and repeat. As you select tasks -notice they get listed on the right. This is the preview pane, it is a view of what will get -scheduled when you're done. When you are satisfied with your selection, press ``Enter`` and all the -tasks in the preview pane will be pushed to try. If you changed your mind you can press ``Esc`` or -``Ctrl-C`` to exit the interface without pushing anything to try. -Unlike the ``syntax`` selector, the ``fuzzy`` selector doesn't use the commit message to pass -information up to taskcluster. Instead, it uses a file that lives at the root of the repository -called ``try_task_config.json``. You can read more information in the :doc:`taskcluster docs -`. +The process for selecting tasks is otherwise the same as for a mouse. A particularly fast and +powerful way to select tasks is to: + +.. code-block:: text + + Write a precise query => Ctrl-A => Alt-Bspace => Repeat + +As before, when you are satisfied with your selection press ``Enter`` and all the tasks in the +preview pane will be pushed to try. If you change your mind you can press ``Esc`` or ``Ctrl-C`` to +exit the interface without pushing anything. -Extended Search +.. note:: + + Initially ``fzf`` will automatically select whichever task is under your cursor. This is a + convenience feature for the case where you are only selecting a single task. This feature will be + turned off as soon as you *lock in* a selection with ``Right-Click``, ``Tab`` or ``Ctrl-A``. + + +Writing Queries --------------- -When typing in search terms, you can separate terms by spaces. These terms will be joined by the AND -operator. For example the query: +Queries are built from a series of terms, each separated by a space. Terms are logically joined by +the AND operator. For example: .. code-block:: text - windows mochitest + 'windows' 'mochitest' + +This query has two terms, and is the equivalent of saying: Give me all the tasks that match both the +term ``'windows'`` and the term ``'mochitest'``. In other words, this query matches all Windows +mochitest tasks. -Will match tasks that have both the terms ``windows`` AND ``mochitest`` in them. This is a fuzzy match so the query: +The single quotes around each term tell ``fzf`` to use exact substring matches, so only +tasks that contain both the literal string ``windows`` AND the literal string ``mochitest`` will be +matched. For convenience, the trailing quote is optional: + +.. code-block:: text + + 'windows 'mochitest + +This query is exactly the same as the one before. + +.. note:: + + From here on out the trailing quote will be omitted from examples. + +Another thing to note is that the order of the terms makes no difference, so ``'windows 'mochitest`` +and ``'mochitest 'windows`` are equivalent. + + +Fuzzy terms +~~~~~~~~~~~ + +If a term is *not* prefixed with a single quote, that makes it a fuzzy term. This means the +characters in the term need to show up in order, but not in sequence. E.g the fuzzy term ``max`` +would match the string ``mozilla firefox`` (as first there is an ``m``, then an ``a`` and finally an +``x``), but not the string ``firefox by mozilla`` (since the ``x`` is now out of order). Here's a +less contrived example: .. code-block:: text wndws mchtst -Would likely match a similar set of tasks. The following modifiers can be applied to a search term: +Like the query above, this one would also select all Windows mochitest tasks. But it will +additionally select: + +.. code-block:: text + + test-macosx1014-64-shippable/opt-talos-sessionrestore-many-windows-e10s + +This is because both sequences of letters (``wndws`` and ``mchtst``) independently appear in order +somewhere in this string (remember the order of the terms makes no difference). + +At first fuzzy terms may not seem very useful, but they are actually extremely powerful! Let's use +the term from the interface image above, ``'linux64 mochibrochr``, as an example. First, just notice +how in the image ``fzf`` highlights the characters that constitute the match in green. Next, notice +how typing ``mochibrochr`` can quickly get us all mochitest browser-chrome tasks. The power of fuzzy +terms is that you don't need to memorize the exact task labels you are looking for. Just start +typing something you think is vaguely correct and chances are you'll see the task you're looking for. + + +Term Modifiers +~~~~~~~~~~~~~~ + +The following modifiers can be applied to a search term: .. code-block:: text @@ -66,7 +169,19 @@ For example: .. code-block:: text - ^start 'exact | !ignore fuzzy end$ + ^start 'exact | 'other !ignore fuzzy end$ + +would match the string: + +.. code-block:: text + + starting to bake isn't exactly fun, but pizza is yummy in the end + +.. note:: + + The best way to learn how to write queries is to run ``mach try fuzzy --no-push`` and play + around with all of these modifiers! + Specifying Queries on the Command Line -------------------------------------- diff --git a/tools/tryselect/docs/selectors/fzf.png b/tools/tryselect/docs/selectors/fzf.png new file mode 100644 index 0000000000000..a64f4b04f3404 Binary files /dev/null and b/tools/tryselect/docs/selectors/fzf.png differ diff --git a/tools/tryselect/mach_commands.py b/tools/tryselect/mach_commands.py index 17d7d563e2e51..37cd3116457ec 100644 --- a/tools/tryselect/mach_commands.py +++ b/tools/tryselect/mach_commands.py @@ -215,11 +215,34 @@ def try_default(self, argv=None, **kwargs): description='Select tasks on try using a fuzzy finder', parser=get_parser('fuzzy')) def try_fuzzy(self, **kwargs): - """Select which tasks to use with fzf. + """Select which tasks to run with a fuzzy finding interface (fzf). + + When entering the fzf interface you'll be confronted by two panes. The + one on the left contains every possible task you can schedule, the one + on the right contains the list of selected tasks. In other words, the + tasks that will be scheduled once you you press . + + At first fzf will automatically select whichever task is under your + cursor, which simplifies the case when you are looking for a single + task. But normally you'll want to select many tasks. To accomplish + you'll generally start by typing a query in the search bar to filter + down the list of tasks (see Extended Search below). Then you'll either: + + A) Move the cursor to each task you want and press to select it. + Notice it now shows up in the pane to the right. + + OR + + B) Press to select every task that matches your filter. + + You can delete your query, type a new one and select further tasks as + many times as you like. Once you are happy with your selection, press + to push the selected tasks to try. + + All selected task labels and their dependencies will be scheduled. This + means you can select a test task and its build will automatically be + filled in. - This selector runs all task labels through a fuzzy finding interface. - All selected task labels and their dependencies will be scheduled on - try. Keyboard Shortcuts ------------------ @@ -227,21 +250,23 @@ def try_fuzzy(self, **kwargs): When in the fuzzy finder interface, start typing to filter down the task list. Then use the following keyboard shortcuts to select tasks: - accept: - cancel: or - cursor-up: or - cursor-down: or - toggle-select-down: - toggle-select-up: - select-all: - deselect-all: - toggle-all: - clear-input: + Ctrl-K / Up => Move cursor up + Ctrl-J / Down => Move cursor down + Tab => Select task + move cursor down + Shift-Tab => Select task + move cursor up + Ctrl-A => Select all currently filtered tasks + Ctrl-D => De-select all currently filtered tasks + Ctrl-T => Toggle select all currently filtered tasks + Alt-Bspace => Clear query from input bar + Enter => Accept selection and exit + Ctrl-C / Esc => Cancel selection and exit + ? => Toggle preview pane There are many more shortcuts enabled by default, you can also define your own shortcuts by setting `--bind` in the $FZF_DEFAULT_OPTS environment variable. See `man fzf` for more info. + Extended Search --------------- @@ -256,6 +281,13 @@ def try_fuzzy(self, **kwargs): For example: ^start 'exact | !ignore fuzzy end$ + + + Documentation + ------------- + + For more detailed documentation, please see: + https://firefox-source-docs.mozilla.org/tools/try/selectors/fuzzy.html """ if kwargs.pop('interactive'): kwargs['query'].append('INTERACTIVE')