-
-
Notifications
You must be signed in to change notification settings - Fork 86
Reporting Issue
When you create a report, please describe the detailed setup and the steps to reproduce it. Since an obvious breakage will soon be fixed, when you face a problem, it is most probably caused only in your specific environment and setup. In fact, when we receive an issue report, we cannot reproduce the problem in most cases.
We cannot investigate the issue as far as the problem does not reproduce, so the first step of the issue discussion would usually be to reproduce the problem in our environment. In this step, we need a detailed setup of your environment that is sufficient to reproduce the problem. However, the information needed to reproduce the problem is unknown until the issue becomes clear, so please be so kind as to understand that the debugging procedure will usually be trial and error and require patience.
This article summarizes the information that can be used to identify the setup related to the problem that you are now facing.
Result of "ble summary"†
When we receive an issue, we ask the result of ble summary to identify the
versions of ble.sh and Bash, and other aspects of the shell environment.
This is important because to fix a problem, we need to reproduce the problem in
our environment, but problems usually appear only with specific setups.
After starting a Bash session in which ble.sh is sourced, you can run the following command to get the result:
$ ble summaryThe same information can also be obtained by pressing
Ctrl-xCtrl-v in the ble.sh session. If you use an older
version of ble.sh, ble summary may not be available. In that case, you can
instead use the following command:
$ ble/widget/display-shell-versionIf you cannot copy and paste the result of the above command because the
terminal does not allow it, please at least manually copy the Bash version (on
the first line) and the version of ble.sh (on the second line, including the
commit hash) in the following form:
GNU bash, version 5.3.0(1)-release (x86_64-pc-linux-gnu)
ble.sh, version 0.4.0-devel4+5b7a6ecb (noarch)
If you cannot run the command ble summary because you cannot correctly source
ble.sh due to the problem, you can instead include the version of ble.sh
(including the commit hash) and the Bash version. The version of ble.sh can be
obtained by running the following command:
$ bash /path/to/ble.sh --versionThe Bash version can be obtained by the following command.
$ echo "$BASH_VERSION ($MACHTYPE)"Including examples in text, image, or video†
You may better explain the situation with the example content of the terminal in either a text form, an image, or a video. However, even when you include those contents, please try to explain the situation also in text. In particular, include "what you did" and "what you expect". One reason is that it becomes hard to search the issue later if the issue only contains the example terminal content. Another reason is that it lacks some contexts if only the example contents are provided.
For example, when ble.sh doesn't do what you expect and nothing happens, the
example content will not show anything. We cannot get information from ae
blank example. It is important to explain what you expect as a result.
For example, when users provide a video, users tend to think the video explains everything about what you did, but that's not true. We cannot tell what you have input from the keyboard while taking the video. Keyboard inputs need to be included in the video, or you need to explain what you have input from the keyboard by text.
To generate completions, ble.sh uses external completion settings that are
configured by the complete builtin of Bash. The completion settings are
provided by the project of each command or the
bash-completion framework. User
can also write their own custom completion settings. These completion settings
are usually only tested within the Bash/Readline environment, but they may
cause problems with ble.sh due to the difference in how the setting is
called. In this section, we summarize relavant discussions.
Errors triggererd by auto-complete†
We recently receive many reports related to external completion settings. The
auto-complete feature of ble.sh attempts to generate candidate words for
every insertion of a character. In this process, it calls the programmable
completion setting. If the external completion setting is broken, or if the
external completion setting tries to perform an operation that ble.sh doesn't
expect, it may cause an error message for every key input or other problems.
- If an error message appears on every key input, it is probably caused by the
auto-completefeature, and it is probably the error caused inside the associated external completion setting. - As another symptom, some of the user inputs can be missing. This can also be
caused by external completion settings that try to read the user's inputs
from TTY when they are called inside the
auto-completefeature. - Even another symptom is that the user input is blocked after a few keys and
ble.shbecomes unresponsive. It might or might not recover the original state by pressing C-c. This can also be caused by external completion settings that hangs insideauto-complete.
To confirm the problem is caused inside auto-complete, one can see if the
problem persists after turning off the auto-complete feature by running the
following command:
$ bleopt complete_auto_complete=If the problem stops happening with the above setting, the problem is caused
inside the auto-complete feature. If the problem persists, the
auto-complete feature is unrelated.
Even when the external completion is used by ble.sh's TAB completion,
compatibility a problem may arise due to the difference between Readline and
ble.sh. Most of the problems are due to issues in the external completion
settings, which does cause an undesirable result even in plain Bash but is
broken more terribly when combined with ble.sh. Some problems are to the
limitation of ble.sh implemented as a shell script, and some are due to
ble.sh's intentional behavioral improvements of the completion. Typical
problems include the following:
- Error messages are printed on attempting a TAB completion. This is not
specific to
ble.shbut should also happen in a Bash session withoutble.sh. - Hanging completion settings cannot be canceled by C-c, which was
possible with Readline. The behavior in Readline is still not ideal as the
current command line will be lost by C-c but is not as bad as in
ble.shwhere there is no way to cancel the external completion. - Interactive interface started by an external completion receives unrecognized
escape sequences. This is due to a terminal mode that
ble.shuses. If the external completion's interface does not support the terminal mode, it may be confused.
Details are described in the next subsection.
There are several types of problems related to how ble.sh calls and uses the
external completion settings. The programmable completion settings by the
complete builtin are provided by Bash for the TAB completion, so the settings
may not work as expected in auto-complete. Nevertheless, as far as the
completion setting simply generates completion candidates, problems should not
happen. A problem would happen when the completion setting tries to
interactively communicate with the user or when the completion setting is
blocked for a long time. The reason that ble.sh still uses the programmable
completion settings, which may be incompatible with ble.sh's completion
environment, to generate completion candidates is that it is impractical to
prepare the completion settings for arbitrary commands by ourselves. Our
current policy is to attempt to use the programmable completion settings by
default, and if a user reports any problems, we patch each completion setting.
For this reason, the users' reports for incompatible programmable completions
are important. However, most of the completion settings is actually
compatible with ble.sh's TAB compeltion and auto-complete fortunately, so
the problem raarely happens.
Broken completion settings: Some completion settings are broken so that
they output error messages to the terminal. In Bash, the error message is
printed only when the user presses TAB to attempt the completion.
The error message is still annoying because it breaks the layout, but the shell
is still usable because the user can press C-l to rerender the
command line. However, such a completion is called in the background by
auto-complete, it will continuously output error messages for every user
input, which makes it almost impossible to use the shell.
This is a bug of the completion setting, and it should be fixed in the
completion setting. One might think that ble.sh should redirect stderr of
the completion setting to /dev/null to suppress the error message, but we
decided not to do it. There are two reasons. If stderr is redirected to
/dev/null, the user would lose a chance to notice the incorrect setup. It is
generally not a good idea to silence error messages without solving them
because the error may cause actual problems instead of just outputting annoying
messages. Another reason is that some completion settings want to render TUI
windows in the terminal through stderr and tries to get a response from the
user. If stderr is redirected to /dev/null, such a completion setting
would wait for the user's action without any visible interface, and it appaers
to hang in the user's perspective.
Hanging completion settings: Some completion settings hangs for a certain
condition or takes a long time to generate the completion settings. In Bash,
when it hangs, the user can press C-c to send SIGINT to the
completion script to cancel it. However, when the completion setting is used
called by ble.sh, C-c is not translated to SIGINT and cannot be
used to cancel the completion. This is because ble.sh is also implemented in
Bash scripts, so the processing of ble.sh would also be canceled by
C-c if the translation of C-c to SIGINT would be
enabled.
This should also be considered a bug of the completion setting. Although one
can technically escape from the hanging state by C-c without
ble.sh, it clears the command line, so the user needs to input the same
string again. In the first place, blocking until the user presses
C-c or requiring users to wait for a very long time would be the
issues with the completion setting. In general, this should be fixed in the
completion setting, though we may add workarounds for such completions.
Completion settings reading stdin: Some completion settings tries to read
data from stdin for interactive interface. Or even if the completion setting
doesn't actually use the input, some of the tools called from the completion
setting tries to flush stdin before terminating. This may not cause a
problem in the TAB completion, but it would cause problems with
auto-complete. For this reason, ble.sh redirects stdin of the completion
setting to /dev/null. If stdin is connected to the terminal, it would
cause missing inputs because it would continuously consume/flush the input
stream, which contains the user's keyboard inputs.
There is another purpose for redirecting stdin to /dev/tty. Some
completion settings such as fzf and skim try to open the TUI window in the
completion. This would be useful with the TAB completion, where the completion
is triggered by the user's request. However, the interactive interface should
not pop up automatically for every single character from the user's input, so
it should be turned off in auto-complete. We expect that tools turn off
their interactive mode when stdin is not connected to a TTY, and that the
redirection of stdin to /dev/tty turns off the interactive mode.
Nevertheless, there are still completion settings that try to open /dev/tty
even when stdin is not connected to a TTY. One needs to adjust the behavior
of such a completion setting.
Interactive completion settings: For interactive completion settings, the
difference between ble.sh's internal/external
states may also cause a problem
in the completion setting. The completion setting is called inside ble.sh's
internal state because the completion is performed in the editor mode (instead
of the command-execution mode). Inside the internal state, the terminal
settings may not be compatible with the interactive completion setting. For
example, inside a terminal with support for an advanced keyboard
protocol,ble.sh turns on the keyboard protocol. However, the interactive
completion setting may not recognize the advanced keyboard protocol, in which
case the completion setting may enter an unresponsive state or start to print
unrecognized codes. This case also requires adjustments of the completion
setting.
You can find related explanations in the following comments: