tools/tryselect/docs/presets.rst

   1 Presets
   2 =======
   3
   4 Some selectors, such as ``fuzzy`` and ``syntax``, allow saving and loading presets from a file. This is a
   5 good way to re-use a selection, either at a later date or by sharing with others. Look for a
   6 'preset' section in ``mach <selector> --help`` to determine whether the selector supports this
   7 functionality.
   8
   9 Using Presets
  10 -------------
  11
  12 To save a preset, run:
  13
  14 .. code-block:: shell
  15
  16     $ mach try <selector> --save <name> <args>
  17
  18 For example, to save a preset that selects all Windows mochitests:
  19
  20 .. code-block:: shell
  21
  22     $ mach try fuzzy --save all-windows-mochitests --query "'win 'mochitest"
  23     preset saved, run with: --preset=all-windows-mochitests
  24
  25 Then run that saved preset like this:
  26
  27 .. code-block:: shell
  28
  29     $ mach try --preset all-windows-mochitests
  30
  31 To see a list of all available presets run:
  32
  33 .. code-block:: shell
  34
  35     $ mach try --list-presets
  36
  37
  38 Editing and Sharing Presets
  39 ---------------------------
  40
  41 Presets can be defined in one of two places, in your home directory or in a file checked into
  42 mozilla-central.
  43
  44 Local Presets
  45 ~~~~~~~~~~~~~
  46
  47 These are defined in your ``$MOZBUILD_STATE_DIR``, typically ``~/.mozbuild/try_presets.yml``.
  48 Presets defined here are your own personal collection of presets. You can modify them by running:
  49
  50 .. code-block:: shell
  51
  52     $ ./mach try --edit-presets
  53
  54
  55 Shared Presets
  56 ~~~~~~~~~~~~~~
  57
  58 You can also check presets into mozilla-central in `tools/tryselect/try_presets.yml`_. These presets
  59 will be available to all users of ``mach try``, so please be mindful when editing this file. Make
  60 sure the name of the preset is scoped appropriately (i.e doesn't contain any team or module specific
  61 terminology). It is good practice to prefix the preset name with the name of the team or module that
  62 will get the most use out of it.
  63
  64
  65 Preset Format
  66 ~~~~~~~~~~~~~
  67
  68 Presets are simple key/value objects, with the name as the key and a metadata object as the value.
  69 For example, the preset saved above would look something like this in ``try_presets.yml``:
  70
  71 .. code-block:: yaml
  72
  73     all-windows-mochitests:
  74         selector: fuzzy
  75         description: >-
  76             Runs all windows mochitests.
  77         query:
  78             - "'win 'mochitest"
  79
  80 The ``selector`` key (required) allows ``mach try`` to determine which subcommand to dispatch to.
  81 The ``description`` key (optional in user presets but required for shared presets) is a human
  82 readable string describing what the preset selects and when to use it. All other values in the
  83 preset are forwarded to the specified selector as is.
  84
  85 .. _tools/tryselect/try_presets.yml: https://searchfox.org/mozilla-central/source/tools/tryselect/try_presets.yml