From b673f32b9380960a879464f63e6c2525f0bf21f8 Mon Sep 17 00:00:00 2001 From: Charles Gould Date: Fri, 15 May 2020 17:54:45 -0500 Subject: [PATCH] Add fish debugging examples --- doc_src/cmds/fish.rst | 23 ++++++++++++++++++++--- doc_src/cmds/fish_indent.rst | 2 +- share/completions/fish.fish | 2 +- 3 files changed, 22 insertions(+), 5 deletions(-) diff --git a/doc_src/cmds/fish.rst b/doc_src/cmds/fish.rst index ecf4fd23f..d7219db62 100644 --- a/doc_src/cmds/fish.rst +++ b/doc_src/cmds/fish.rst @@ -13,7 +13,7 @@ Synopsis Description ----------- -``fish`` is a command-line shell written mainly with interactive use in mind. This page briefly describes the options for invoking fish. The :ref:`full manual ` is available in HTML by using the :ref:`help ` command from inside fish, and in the `fish-doc(1)` man page. The :ref:`tutorial ` is available as HTML via ``help tutorial`` or in `fish-tutorial(1)`. +fish is a command-line shell written mainly with interactive use in mind. This page briefly describes the options for invoking fish. The :ref:`full manual ` is available in HTML by using the :ref:`help ` command from inside fish, and in the `fish-doc(1)` man page. The :ref:`tutorial ` is available as HTML via ``help tutorial`` or in `fish-tutorial(1)`. The following options are available: @@ -21,9 +21,9 @@ The following options are available: - ``-C`` or ``--init-command=COMMANDS`` evaluate the specified commands after reading the configuration, before running the command specified by ``-c`` or reading interactive input -- ``-d`` or ``--debug=CATEGORY_GLOB`` enables debug output and specifies a glob for matching debug categories (like ``fish -d``). Defaults to empty. +- ``-d`` or ``--debug=DEBUG_CATEGORIES`` enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging ` below for details. -- ``-o`` or ``--debug-output=path`` Specify a file path to receive the debug output, including categories and ``fish_trace``. The default is stderr. +- ``-o`` or ``--debug-output=DEBUG_FILE`` specify a file path to receive the debug output, including categories and ``fish_trace``. The default is stderr. - ``-i`` or ``--interactive`` specify that fish is to run in interactive mode @@ -46,3 +46,20 @@ The following options are available: - ``-f`` or ``--features=FEATURES`` enables one or more :ref:`feature flags ` (separated by a comma). These are how fish stages changes that might break scripts. The fish exit status is generally the :ref:`exit status of the last foreground command `. + +.. _debugging-fish: + +Debugging +--------- + +While fish provides extensive support for :ref:`debugging fish scripts `, it is also possible to debug and instrument its internals. Debugging can be enabled by passing the ``--debug`` option. For example, the following command turns on debugging for background IO thread events, in addition to the default categories, i.e. *debug*, *error*, *warning*, and *warning-path*:: + + > fish --debug=iothread + +Available categories are listed by ``fish --print-debug-categories``. The ``--debug`` option accepts a comma-separated list of categories, and supports glob syntax. The following command turns on debugging for *complete*, *history*, *history-file*, and *profile-history*, as well as the default categories:: + + > fish --debug='complete,*history*' + +Debug messages output to stderr by default. Note that if ``fish_trace`` is set, execution tracing also outputs to stderr by default. You can output to a file using the ``--debug-output`` option:: + + > fish --debug='complete,*history*' --debug-output=/tmp/fish.log --init-command='set fish_trace on' diff --git a/doc_src/cmds/fish_indent.rst b/doc_src/cmds/fish_indent.rst index 74be5d152..ffc15d29f 100644 --- a/doc_src/cmds/fish_indent.rst +++ b/doc_src/cmds/fish_indent.rst @@ -28,7 +28,7 @@ The following options are available: - ``--html`` outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as ``fish_color_command``. -- ``-d`` or ``--debug=CATEGORY_GLOB`` enables debug output and specifies a glob for matching debug categories (like ``fish -d``). Defaults to empty. +- ``-d`` or ``--debug-level=DEBUG_LEVEL`` enables debug output and specifies a verbosity level. Defaults to 0. - ``-D`` or ``--debug-stack-frames=DEBUG_LEVEL`` specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128. diff --git a/share/completions/fish.fish b/share/completions/fish.fish index e70d2ad05..deb2d4e32 100644 --- a/share/completions/fish.fish +++ b/share/completions/fish.fish @@ -6,7 +6,7 @@ complete -c fish -s n -l no-execute -d "Only parse input, do not execute" complete -c fish -s i -l interactive -d "Run in interactive mode" complete -c fish -s l -l login -d "Run as a login shell" complete -c fish -s p -l profile -d "Output profiling information to specified file" -r -complete -c fish -s d -l debug -d "Specify verbosity level" -x -a "0\t'Warnings silenced' +complete -c fish -s d -l debug -d "Specify debug categories" -x -a "0\t'Warnings silenced' 1\t'Default' 2\t'Basic debug output' 3\t'More debug output'