BashSupport Pro adds advanced features for shell scripts to your JetBrains IDE. You can debug Bash scripts, run bats-core tests and work efficiently with shell scripts.

Debugging a Bash script in IntelliJ with BashSupport Pro
Debugging a Bash script in IntelliJ with BashSupport Pro

Running bats-core tests in IntelliJ with BashSupport Pro
Running bats-core tests in IntelliJ with BashSupport Pro

Introduction to BashSupport Pro

BashSupport Pro is a plugin to provide a complete Bash editing environment. It complements JetBrains Shell plugin and adds missing functionality on top.

BashSupport Pro is compatible with all IDEs of the IntelliJ platform, versions 2019.3 or later. This includes IntelliJ IDEA Community and Ultimate, PyCharm, WebStorm, GoLand, and others.

The plugin is made by the author of the open-source BashSupport plugin. It builds on the experience gained by building and maintaining the open–source plugin for the past 10 years. This plugin is now retiring — JetBrains is shipping its own Shell Script plugin and maintaining the open-source plugin for another decade seems impossible to me.

What you get

With BashSupport Pro you get highly useful features like a Bash debugger.

BashSupport Pro is still a young software — it’ll grow older and more mature in the next months.

Features of BashSupport Pro

The BashSupport Pro plugin is in its early states and under active development. Therefore this list will grow with the next versions of BashSupport Pro.

BashSupport Pro relies on either the open–source BashSupport plugin or JetBrains’s Shell plugin for the basic functionality.

This is what BashSupport Pro adds to your IDE:

BashSupport Pro
+ JetBrains Shell
BashSupport Pro
+ BashSupport
Debug Bash Scripts
Bash v5 and v4 on macOS, Linux, Windows  more
bats-core Test Runner
Run configuration, editor support, live templates, new file action
macOS, Linux, Windows  more
New File Action
Smart new file action  more
Code Folding
Folding for grouping elements  more
Custom Code Folding
Vim-style {{{...}}}  more
Support For The Source Command
Go to source, updates file reference after rename and move operations  more
Support For The Shellcheck Source Directive
Go to source, updates file reference after rename and move operations  more
×
Go To Symbol
Available for function and variable definitions  more
×
Basic Intentions
quote, unquote, escape, unescape  more
Spellcheck Support
Bundled dictionaries with common bash, GNU, and POSIX commands  more
= provided by BashSupport Pro    = already provided by the plugin

How BashSupport Pro Is Sold

BashSupport Pro is available on the JetBrains marketplace.
JetBrains handles licenses, payment, and infrastructure.

Subscription With a Fallback License

BashSupport Pro uses a subscription model with a fallback license. You get a perpetual license after 12 months of payment. JetBrains is using the same model for IntelliJ. Read more about the fallback license at jetbrains.com.

Pricing

Types of Licenses

There are several types of licenses available for BashSupport. Because the plugin is sold on the JetBrains Marketplace, the available types are the same as for the JetBrains IDEs.

Here’s an overview. You could also check JetBrains’s comparision chart and JetBrains’s FAQ.

Free Licenses for Contributors

Have you contributed to the open–source BashSupport plugin in the past? Then you qualify for a free, 1–year license.

Comparision of BashSupport and JetBrains Shell

The foundation for BashSupport Pro is provided by either open–source BashSupport or JetBrains Shell. You need to choose which plugin you’d like to use. Only one of the two plugins must be enabled.

Personal recommendation
At this time, I recommend to use BashSupport Pro together with the open–source BashSupport plugin. Editing experience is best with this combination of plugins.
JetBrains Shell plugin is rapidly improving and soon will be the preferred choice. The support for the open–source BashSupport plugin will be dropped as soon as JetBrains Shell + BashSupport Pro is providing a similar or better editing experience.

JetBrains Shell still has advantages. Internally it has a better implementation than BashSupport. For example, it handles large Bash scripts with less delay in the editor.

Comparision table

Please note, that this comparision is meant for users, who edit scripts most of the time.

BashSupport
for 2019.3
JetBrains Shell
for 2019.3
Compatible with BashSupport Pro
BashSupport Pro requires an IDE version 2019.3 or later.
Rename variables
JetBrains Shell renames all variables of the same name, even if it’s a different variable.
For example, local variables are not renamed correctly.
×
Rename functions
JetBrains Shell renames all functions of the same name, even if it’s a different function.
×
Resolve references
This is used for ‘Go to definition’, ‘Show Definition’ and other features.
×
source command support
Rename, go to definition, and others for elements in sourced files.
×
Language injection
×
Code folding
×
Highlight usages
JetBrains Shell highlights by text occurrence.
Variables, functions, and string content are hightlighted at the same time.
 limited
Heredoc support
JetBrains Shell isn’t supporting heredocs without parameter substitution.
 limited
Documentation lookup
BashSupport supports ‘man’, ‘info’, and comments in the source.
Shell only supports ‘info’.
 limited
Code completion
Shell is suggesting word–based.
Function names are suggested for variables, for example.
 limited
Formatter
JetBrains Shell uses shfmt.
×
Indent lines
×
Highlight URLs in strings
×
explainshell integration
×
Syntax Highlighting
Brace Matching
Structure view
Execute scripts
BashSupport creates a new tool window.
JetBrains Shell executes in a Terminal tool window.
ToDo highlighting
Spellcheck support
Inspections
Both have different inspections.
JetBrains Shell uses shellcheck and thus provides more inspections.
Live templates
Both plugins bundle a different set of live templates.
Support Bash scripts without file extensions

Where to get help and support

Bug Reports & Feature Requests
Use the GitHub project at github.com/bashsupport-pro.
Community Forum
There’s a community forum at discuss.bashsupport.com.
Personal Contact
You can always send me a message at plugin-dev.com.

Free License for all BashSupport Contributors

Have you contributed to the open–source BashSupport plugin?
Then you are eligible for a free, 1-year license.

Before BashSupport Pro there was the open–source BashSupport plugin, which now is in its retirement. Please refer to this post and this follow–up post to learn why this happened.

BashSupport Pro wouldn’t be possible without the experience gained from the open–source BashSupport plugin. Many users contributed by creating bug reports, feature requests or submitting pull requests.

Therefore I’ll send every contributor, who requests it, a free license for a year.
I’ve counted 238 different contributors in total!

Eligible Contributors

These contributions count:

  • Pull Requests, created before 2020–02–22
  • New issues, created before 2020–02–22

Is your contribution not included or do you think that you still should get a free license? Please send me a message at mail@bashsupport.com and I’ll see what I can do.

How to Request Your Free License

  1. Enter your GitHub user name:
    This updates the two links below.
  2. Check these links. If at least one item older than 2020-02-22 is listed on one these two pages, then you’re eligible for a free license.
  3. If you’re eligible: send me an email at free@bashsupport.com — please don’t forget to insert your GitHub user name.
    If possible, send it from the address which is linked to your GitHub account.
  4. I’ll send you a coupon to get your free license on the JetBrains marketplace. If I can’t verify that you own the given GitHub account, then I’ll send you an invite to join a private repository.
    Give a few days to handle all the messages, please :)

Frequently Asked Questions about BashSupport Pro

Why was BashSupport Pro made?
It was made because JetBrains created its own Shell plugin and because maintaining the open–source BashSupport plugin became impossible with available time and reesources.
Please refer to this post and this follow–up post to learn more about this.

Privacy of BashSupport Pro

BashSupport Pro never sends metrics without your consent. A notification is displayed at startup to ask for your consent. If you don’t opt–in to metrics, then nothing will be send.

Telemetry data is a small piece of data to tell what’s happening and which features are used or unused. Data is send in the form of “events”. An event is send when something happens, e.g. when the Bash debugger was started.

Please note, that preview and beta versions of the plugin always send telemetry data.

Error Reporting

Exception reports are also send to the Sentry application above. Only the information which you entered into the dialog is send. Please note, that the common properties shown above are also send with the error report.

Transmitted Data

The following section shows exactly what’s send. This list displays the data, which is used by the latest public release of BashSupport Pro.

I’m no aware of any other company offering such a list. Personally I strongly dislike tracking. I need some data to make sure BashSupport Pro is developing into the right direction — therefore I’m tracking software, not people. I try to be very open about what’s going on under the hood.

Common Properties

These are the properties which are send with every event.

PropertyDescription
datetime
Example: 2020-01-30T21:33:14.000000Z
Timestamp when the event is send to the server.
release
Example: 1.0.0
The installed version of the BashSupport Pro plugin
platform
Example: java
Name of the used software platform, used internally by Sentry.
environment
Example: eap
A string to tell if the plugin is a development or stable version
jdk.vendor
Example: JetBrains
The vendor of the Java runtime used to execute the IDE.
jdk.version
Example: 11.0.4+10-b520.11
Version of the Java runtime used to execute the IDE.
os.name
Example: Windows
The name of the operating system you're using.
os.version
Example: 10.15.1
The version of the operating system you're using.
ide.type
Example: IU
The product code of your IDE.
ide.major
Example: 2019
The major build number of your IDE.
ide.build
Example: IU-193.6015.39
The full build id of your IDE.
plugin.shell
Example: true
A boolean value to tell if the JetBrains Shell plugin is used with BashSupport Pro.
plugin.bashsupport
Example: true
A boolean value to tell if the open-source BashSupport plugin is used with BashSupport Pro.

Event Properties

These are the events and properties which are send. The common properties are send with each event, but not listed again. You can expand the “Properties” sections to see the properties of a specific event.

EventDescription and properties
app_startingFired when the IDE is starting and the BashSupport Pro plugin is initialized
Properties
plugin_id (example: “pro.bashsupport”)
The ID of the BashSupport Pro plugin
licensed (example: “true”)
Boolean value if a license is found for the plugin
test_batsFired when a bats-core run configuration is executed
Properties
name_filter (example: “false”)
Boolean value to tell if the run configuration is filtering tests by name
recursive (example: “true”)
Boolean value to tell if the run configuration is recursively search for tests
parallel (example: “1”)
Integer value to tell how many tests are executed in parallel
path_mapper (example: “Automatic”)
The path mapping used for this run configuration
debug_session_pausedFired when a Bash debug session stopped at a breakpoint.
debug_session_resumedFired when a Bash debug session was resumed.
debug_session_startedFired when a new debug session was started
Properties
file_ext (example: “sh”)
File extension of the debugged file
debug_session_stoppedFired when a Bash debug session terminated, either successfully or with an error.
intentionFired when an intention of BashSupport Pro was applied in a file
Properties
intention_name (example: “ConvertToQuotedString”)
The ID of the applied intention
new_file_actionFired when a new shell script file has been created using BashSupport Pro's new file action
Properties
template (example: “BashSupport Pro Bash”)
Name of the file template
file_ext (example: “bash”)
The file extension of the new file
unlicensed_actionFired when a feature is executed, but no valid license was found. A stack trace is included in the event data.

End User License Agreement of BashSupport Pro (“EULA”)

“Developer” means the author of BashSupport Pro: Joachim Ansorg, Am Sonnenrain 76, 79539 Lörrach, Germany.

“JetBrains” means JetBrains s.r.o. with its registered office at Na Hřebenech II 1718/10, Prague, 14000, Czech Republic, registered with the Commercial Register kept by the Municipal Court of Prague, Section C, file 86211, ID.Nr.: 265 02 275.

“JetBrains Affiliate” means the subsidiary and/or any associated companies of JetBrains.

“JetBrains Marketplace” means any platform operated by JetBrains or a JetBrains Affiliate on which JetBrains or a JetBrains Affiliate markets Plugins for JetBrains Products, including the website https://plugins.jetbrains.com and/or any other website or other platform, whether named JetBrains Marketplace, JetBrains Plugins Repository, or otherwise.

“JetBrains Product” means any software program or service made available by JetBrains.

“Plugin” means the Plugin for JetBrains Product that Developer makes available under this EULA.

“Plugin Information” means the following information and materials: (a) JetBrains Marketplace Plugin title, tags / category, name(s) of Developer(s), product description, icon, logo or banner images, and any other information related to Plugins; (b) the metadata, graphics, artwork, images, trademarks, trade names, logos and other descriptive or identifying information and materials associated with Developer or appears in connection with Plugin; and (c) in the case of cloud hosted Plugins, an XML/JSON descriptor of Plugin.

“Plugin Users” means users that are able to access and use Plugin concurrently.

“You” means an individual or an entity concluding this EULA.

This EULA governs the terms of use of Plugin made available to You via JetBrains Marketplace. This EULA is entered into between You and Developer.

If Plugin is a paid Plugin, you must ensure that the maximum number of Plugin Users does not exceed the number of Plugin Users for which you have purchased Plugin.

You are authorized to use Plugin in accordance with its documentation provided by Developer and for the period of time specified by Developer.

You may not modify, reverse-engineer, decompile, or disassemble Plugin in whole or in part, or create any derivative works from Plugin, or sublicense any rights in Plugin, unless otherwise expressly authorized in writing by Developer.

Plugin is protected by copyright and other intellectual property laws and treaties. Developer or its licensors own all title, copyright and other intellectual property rights in Plugin.

ALL PLUGINS ARE PROVIDED TO YOU ON AN “AS IS” AND “AS AVAILABLE” BASIS WITHOUT WARRANTIES. USE OF PLUGINS IS AT YOUR OWN RISK. DEVELOPER MAKES NO WARRANTY AS TO PLUGIN’S USE OR PERFORMANCE. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, DEVELOPER DISCLAIMS ALL OTHER WARRANTIES AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO PLUGINS, AND THE PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES. DEVELOPER DOES NOT WARRANT THAT PLUGINS ARE ACCURATE, RELIABLE, OR CORRECT; THAT PLUGIN MEETS YOUR REQUIREMENTS; THAT PLUGINS WILL BE AVAILABLE AT ANY PARTICULAR TIME OR LOCATION, UNINTERRUPTED, OR SECURE; THAT ANY DEFECTS OR ERRORS WILL BE CORRECTED; OR THAT PLUGINS ARE FREE OF VIRUSES OR OTHER HARMFUL COMPONENTS.

IN NO EVENT WILL DEVELOPER BE LIABLE FOR ANY DIRECT OR INDIRECT COSTS, LOSSES, OR DAMAGES ASSOCIATED WITH THE USE OF DEVELOPER’S PLUGINS.

DEVELOPER SHALL NOT BE LIABLE TO YOU FOR ANY LOST PROFITS OR CONSEQUENTIAL DAMAGES, HOWEVER CAUSED, AND IN NO EVENT WILL DEVELOPER’S AGGREGATE LIABILITY ARISING OUT OF OR RELATED TO THIS AGREEMENT OR THE USE OF PLUGIN EXCEED THE FEES WHICH YOU PAID VIA JETBRAINS PLUGIN MARKETPLACE SERVICE FOR PLUGINS IN THE THREE-MONTH PERIOD PRECEDING THE CLAIM. THIS LIMITATION WILL APPLY EVEN IF DEVELOPER HAS BEEN ADVISED OF THE POSSIBILITY OF THE LIABILITY EXCEEDING THE AMOUNT AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY. JETBRAINS’ LIABILITY IS EXCLUDED IN ITS ENTIRETY AS JETBRAINS IS NOT A PARTY TO THE CONTRACTUAL RELATIONSHIP BETWEEN DEVELOPER AND CUSTOMER.

Software used by BashSupport Pro

BashSupport Pro wouldn’t be possible without a strong foundation of open–source software. The bundled or used software is listed here.

bashdb (standalone software, bundled)
© 2003, 2006–2007, 2016 Rocky Bernstein
GNU GENERAL PUBLIC LICENSE
bashdb is a wonderful piece of software. It provides the foundation for the debugger integration. BashSupport Pro bundles versions 4.4 and 5.0 of bashdb. These versions are slightly modified to improve interoperability with BashSupport Pro. Most of the changes were already submitted to the SourceForge project page.
All changes are available online:
bats-core (standalone software, bundled)
© 2017-2020 bats-core organization, © 2011-2016 Sam Stephenson
MIT style license
bats-core is a great system to automate tests of Shell and Bash scripts. BashSupport Pro bundles a slightly customized version to improve interoperability with BashSupport Pro.
All changes are available online: https://github.com/BashSupport-Pro/bats-core/tree/bashsupport-pro
pty4j (library, bundled)
Eclipse Public License, version 1.0
pty4j is JetBrains’s library to implement pseudo terminal devices on Linux, macOS and Windows. The included library is a slightly modified version implement a separate PTY for the bashdb command control.
All changes are available online: https://github.com/BashSupport-Pro/pty4j

Install an IDE

  1. Pick your IDE.
    Most likely you’re already using a JetBrains IDE. If not, then you need to pick an IDE. BashSupport Pro is available for all IntelliJ–based IDEs. Pick IntelliJ Community or PyCharm Community if you’d like a free version.
  2. Install BashSupport Pro
  3. Choose the supporting plugin. Follow one of these steps:
  4. Restart your IDE to apply the changes

Install BashSupport Pro

  1. Open the plugin settings File > Settings... > Plugins
  2. Enter BashSupport Pro in the text input field to quickly locate it.
    BashSupport Pro on the JetBrains Marketplace
    BashSupport Pro on the JetBrains Marketplace
  3. Click the Install button to download it

Now you need to decide if you want to use the Pro plugin together with the open–source BashSupport or with JetBrains’s Shell plugin. The comparision of BashSupport vs. JetBrains Shell might help you to pick the right one. At this time, using BashSupport Pro together with BashSupport is recommended.

Using BashSupport Pro with BashSupport

This section explains how to install BashSupport from the marketplace. You only need to do this if you decided to use BashSupport instead of JetBrains Shell.

  1. Open the plugin settings File > Settings... > Plugins
  2. Enter BashSupport into the search box of the marketplace tab.
    How to install BashSupport alongside BashSupport Pro
    How to install BashSupport alongside BashSupport Pro
  3. Click the button Install of the BashSupport item
    How to install BashSupport alongside BashSupport Pro
    How to install BashSupport alongside BashSupport Pro
  4. Make sure that the JetBrains Shell plugin is disabled.
    Enter Shell Support into the search box of the Installed tab. Uncheck the checkbox next to the Shell plugin, if it’s enabled.
    How to disable the JetBrains Shell plugin in your IDE
    How to disable the JetBrains Shell plugin in your IDE
  5. Restart your IDE to activate BashSupport and BashSupport Pro

Using BashSupport Pro with JetBrains Shell

This section explains how to activate the JetBrains Shell plugin. You only need to do this if you decided to use JetBrains Shell instead of BashSupport. The Shell plugin is bundled with your IDE, so you don’t have to install it. But you may have to enable it.

  1. Open the plugin settings File > Settings... > Plugins
  2. Enter Shell Script into the search box of the marketplace tab.
    How to locate the JetBrains Shell plugin in your IDE
    How to locate the JetBrains Shell plugin in your IDE
  3. Enable the JetBrains Shell plugin, if it’s not yet enabled.
    How to enable the JetBrains Shell plugin in your IDE
    How to enable the JetBrains Shell plugin in your IDE
  4. Restart your IDE to activate the Shell plugin and BashSupport Pro

How to manually install BashSupport Pro

This is how you install BashSupport Pro with a file on disk. Most likely, you have a download link and would like to install the plugin. The plugin is provided as a zip file.

  1. Download the zip archive. In our example, it’s saved at /bashsupport-pro/Downloads/bashsupport-pro-0.9.0.beta1.zip.
  2. Open the plugin manager: File > Settings... > Plugins
  3. Choose Install Plugin from Disk... from the gear popup menu
    How to manually install BashSupport Pro
    How to manually install BashSupport Pro
  4. Select the downloaded zip file and click Ok.
    Choosing the BashSupport zip file
    Choosing the BashSupport zip file
  5. Click on the button Restart IDE, which is now visible in the plugin manager.
    Plugin manager after you installed BashSupport Pro
    Plugin manager after you installed BashSupport Pro
  6. Now choose the supporting plugin. Follow one of these steps:

Editor

BashSupport Pro improves the Bash editing experience.
BashSupport Pro is still young, the feature set will grow over time.

Supported File Types

BashSupport Pro supports the following file extensions:

  • *.sh
  • *.bash
  • *.zsh
    The JetBrains Shell plugin assigned this extension to the Shell file type. Improved support for zsh shell may come with later versions of BashSupport Pro.

The following file names open in the Bash editor:

  • .bashrc
  • .profile
  • .bash_profile
  • .bash_logout
  • .bash_aliases

Code Folding

BashSupport Pro adds code folding to the Shell plugin.

Custom folding regions
Vim’s default markers are supported in addition to IntelliJ’s custom markers.
Multi–line comments
All multi–line comments, which are not attached to a function, are collapsed.
Function comments
All comments, which are attached to a function, are collapsed. A sequence of comments, which is immediately followed by a function definition, is attached to this function.
Function blocks
Blocks, which define the body of a function, are collapsed.

Code Folding Settings

Here you can configure the default behaviour of code folding. The checked elements will be folded by default.

How to configure code folding of BashSupport Pro
How to configure code folding of BashSupport Pro

Custom Code Folding

Vim’s default markers are supported in addition to IntelliJ’s custom markers.

Intentions

You can click on the screenshots to learn more about this particular intention.

This intention replaces a single–quoted string `content` to the equivalent, double-quoted "content".

Valid context

This intention is available on all single–quoted strings.

Transformation

Some parts of a single–quoted string need to be escaped to be valid in a double-quoted string. For example, '$noVariable' is transformed into "\$noVariable".

This intention replaces a double–quoted string "content" to the equivalent, single-quoted `content`.

Valid context

This intention is available on all double–quoted strings with static values.

A string with a variable reference, a subshell and other evaluated parts are excluded from this intention.

Transformation

Some parts of a double–quoted string need to be unescaped to represent the same value in a single-quoted string. For example, "\$noVariable" is transformed into '$noVariable'.

This intention escapes a string. It replaces unescaped characters (\\n) with the equivalent, escaped value (\n).

Valid context

This intention is available on all non–empty, double–quoted strings, which contain escapable characters.

This intention unescaped a string. It replaces escaped characters (\\n) with the equivalent, unescaped value (\n).

Valid context

This intention is available on all double–quoted strings, which contain escaped characters.

Go to Symbol

BashSupport Pro implements NavigateSymbol… This feature is only provided for the JetBrains plugin.

How to navigate to a Bash function by name
How to navigate to a Bash function by name

The typical use case is that you know the name of a Bash function, but not where it’s defined. Call NavigateSymbol… and enter the first few characters of the name. BashSupport will fill in the matching functions. Press Enter to navigate to a particular item.

Navigate by function name
Enter the name of the function you’re looking for. If a file contains multiple definitions, then all will be shown in the list.
Navigate by variable name
Enter the name of the variable you’re looking for. If a file contains multiple definitions of the same name, then only the first one is shown in the list.

Sourced Files

BashSupport Pro supports the source command. NavigateGo to Declaration is available on the filename.

Shellcheck Support

Source Directive

1
source "$(dirname "${BASH_SOURCE[0]}")/../other.sh"

BashSupport Pro supports Shellcheck’s source directive. This directive is useful for filenames, which are not static. ../other.sh is a static value, but "$(dirname "${BASH_SOURCE[0]}")/../other.sh" is not. Shellcheck and BashSupport Pro only understand static values.

If you use a dynamic value in script, then you can use the shellcheck source directive to define the static location:

1
2
# shellcheck source=../other.sh
source "$(dirname "${BASH_SOURCE[0]}")/../other.sh"

BashSupport Pro assumes that the source path is relative to the current file. By default, Shellcheck uses the directory where it’s executed as root for source paths. Use the source-path directive or execute shellcheck -P ... if this is a problem in your setup.

Go to Declaration
You can navigate to the source files by ctrlclick or by using the NavigateGo to Declaration action.
Rename
The source= path is updated when you rename the referenced file. It’s also updated when you move the file, which contains the source directive.

Move File Refactoring

References to files are automatically updated when you rename or move them. They’re also updated when you move the file, which contains these references.

Sourced Files

Files referenced by the source command are updated. These different kinds of file references are supports:

1
2
3
4
5
6
. file.bash
. "file.bash"
. 'file.bash'
. ./file.bash
. "filename with whitespace.sh"
. /etc/bash.bashrc

Shellcheck Source Directive

Files referenced by the source command are updated when you move or rename a file. Please refer to the page about Shellcheck for further details.

Bundled Dictionaries

BashSupport Pro comes with a few bundled dictionaries to help you write clean scripts. Refer to JetBrains help pages to learn more how the spellchecker works in your IDE.

With the bundled dictionaries your IDE now accepts the most common commands. You won’t get a warnings when you use the ulimit command in a Shell script, for example.

bashpro.dic — Common words
This small dictionary adds a few common words, which are not in the other bundled dictionaries.
bashpro-bash.dic — Bash builtins
The dictionary bashpro-bash.dic adds the names of all Bash v5 commands. Commands like getopts or ulimit won’t be highlighted for incorrect spelling anymore.
bashpro-posix.dic — POSIX commands
The dictionary bashpro-posix.dic adds the names of all POSIX Shell and utility commands. These commands are not necessarily on your system, but they’re commonly used in scripts.
bashpro-gnu.dic — GNU commands
The dictionary bashpro-gnu.dic adds the names of common GNU command line utilities. For example, chroot is now accepted by the spellchecker.

Debugging Bash scripts with BashSupport Pro

BashSupport Pro adds a debugger for Bash 4 and Bash 5 scripts. It’s using bashdb internally. It integrates many of the available functionality with the debugger interface of your IDE.

This page provides an overview of the debugger. Please refer to the sub–sections for a more detailed documentation of the debugging functionality.

Bash

Versions 5.x and 4.x are supported on macOS, Linux, and Windows.

Version 3.x and older isn’t supported by bashdb. macOS comes with version 3.2, which was released in 2006. Please update to a newer version to use the debugger integration of BashSupport Pro. You can do this via Homebrew, for example.

Supported configurations

Linux and macOS
Two consoles are available. The first one is to interact with your script (stdin and stdout). The second console is used to seperate the communication with bashdb from the regular input and output of the debugged script.
Windows: WSL, Git Bash, Cygwin Bash
At this time, only one console is supported. Input and output will be shared between the debugged script and the bashdb debugger.

How to start the debugger

The debugger is launched like any other debugger integration in your IDE.

Either right click on the editor and choose “Debug script.sh” from the context menu. Or click on the debug symbol next to a run configuration in the navigation toolbar.

How to stop the debugger

This follows the same logic as with any other debugger integration. Just click on the stop icon in the navigation toolbar or in the debugger tool window.

Breakpoints

Breakpoints work like other breakpoints of your IDE.

How to set breakpoints

The easiest way to set a new breakpoint is to use the gutter on the left:

Bash script without breakpoint
Bash script without breakpoint

Click into the empty space on the left. A breakpoint is displayed like this:

Bash script with a breakpoint
Bash script with a breakpoint

Once you start the debugger, an active breakpoint has an additional check mark:

Bash script with an active breakpoint
Bash script with an active breakpoint

How to remove breakpoints

Click on the breakpoint icon to remove it.

Limitations

At this time, only line breakpoints are supported. You can only set breakpoints on non–empty lines.

A breakpoint is only stopping execution for the first instruction on a line. You can’t step over multiple instructions on the same line.

Conditional breakpoints

A conditional breakpoint only stops the execution when the conditional evaluates to true.

To set a condition on a breakpoint:

  1. Right–click on the breakpoint icon
  2. Enter the condition into the text input field
  3. Close the popup to apply the settings
    How to configure a conditional breakpoint in BashSupport pro
    How to configure a conditional breakpoint in BashSupport pro

A conditional breakpoint is marked with a question mark:

An active, conditional breakpoint is marked with an additional check mark:

Examples of conditional breakpoints
The script stops at the breakpoint when the condition evaluates to true (i.e. 0). Here are a few examples:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# stop execution when the value of $name equals "foo"
test $name = "foo"
# same as above
[ $name = "foo" ]

# stop execution when the value of $name begins with "fo"
[[ $name =~ "fo" ]]

# stop execution when the value of $num is a number greater than 120
[[ $num -gt 120 ]]
Conditional breakpoints in BashSupport Pro
Conditional breakpoints in BashSupport Pro

Temporary breakpoints

A temporary breakpoint is removed as soon as it’s hit.

  1. Right–click on a breakpoint
  2. Mark the checkbox Remove after first hit (temporary breakpoint)
    A temporary breakpoint in BashSupport Pro
    A temporary breakpoint in BashSupport Pro

How to configure breakpoints

Your IDE provides a list of the breakpoints. This dialog also allows you to configure the properties of each breakpoint.

Breakpoint settings dialog
Breakpoint settings dialog

Watches

Watches allow you to quickly evaluate expressions while you step through your script.

How to add a new watch expression
How to add a new watch expression

By default, watches are displayed in the variables view. Alternatively, you can configure the view to display watches in a separate panel on the right. Please refer to the IntelliJ documentation for instructions.

The watches are automatically updated when you step through your script.

Evaluated watches while debugging a Bash script in IntelliJ
Evaluated watches while debugging a Bash script in IntelliJ

Your IDE provides several actions to navigate through your script.

Buttons to navigate through your Bash scripts
Buttons to navigate through your Bash scripts

Show execution point
This action opens an editor at the position where the script is currently stopped.
Step over
This action steps over the current line.
Please note that the current implementation is different to the usually expected behaviour. The execution does not stop at breakpoints, which are set inside of functions called on the current line.
Force step over
This actions steps over the current line and ignores any breakpoint set inside of functions called on the current line. Please note, that this action is identical to Step over due to the limitations noted above
Step into
This action steps into the first function call on the current line.
Step out
This action resumes until the execution of the current function is finished.
Run to cursor
This action resumes the execution of the script until the script reaches the marked line. Breakpoints may be hit before the position is reached.
Force run to cursor
Same as above, but all breakpoints are ignored.

Stack and Frames

The list of frames displays the current call stack. A single element, i.e. a line in the screenshot, is called a “frame”. The first element is the top frame. Each frame represents an invocation of a function or a script.

List of stack frames
List of stack frames

The background color of a frame signals its type:

  • a colored background tells you that its source is located in the bashdb sources. This is outside of your script.
  • a transparent background tells you that it’s your own script
    List of stack frames with two frames from bashdb
    List of stack frames with two frames from bashdb

Variables View

The variables view displays variable names and values.

A click on a frame updates the variables view on the right:

The variables view
The variables view

The top frame supports these elements:

  • the arguments to the function or script of the frame
  • the available variables and values

All other frames only support the list of arguments, i.e. they do not support the list variables.

Variable type

Array and associative array
Arrays and associative arrays (aka maps) can be expanded to display the contained elements line by line.
Elements of an array and an associative array
Elements of an array and an associative array
Number
Variables declared via declare -i or local -i are integers, values are displayed as numeric values.
String
All other variables are of type String, the values displayed in quotes.

How to view all available variables

By default only the variables modified by your script are displayed. A snapshot of all available variables is captured before the script is executed. Variables, which still have their initial values, are hidden by default.

You can configure the view to display all available variables.

  1. Click on the gear symbol on the left of the list of frames
  2. Check the option Show environment variables.
    All variables in the variables view
    All variables in the variables view

Evaluate Expressions

Evaluate an expression with the Bash debugger
Evaluate an expression with the Bash debugger

Evaluate Expression... allows to to inspect the current state of your program. Once your scripts stops at a breakpoint, you can use the action Run > Evaluate Expression... to inspect it.

It works like the echo command. It evaluates and prints the expressions you enter into this dialog. That’s why you need to prefix variables with the dollar sign $ and why you need to quote string values.

Examples

Here are some examples for the evaluate expression feature:

1
2
3
4
5
6
7
$name
${name}

${name:-"Default value"}

${arrayVar[0]}
${arrayVar["element name"]}

Limitations

At this time, the evaluate expression dialog only allows to print values. It doesn’t support modifications.

Using the Bashdb console

On Linux and macOS, BashSupport provides two different terminals. One is for your script, the other one to interact with the debugger. bashdb provides features, which are not yet used by BashSupport Pro. Please refer to the bashdb handbook to learn more about the supported commands.

The second terminal is hidden by default. You can turn it on by selecting bashdb console from the layout settings menu.

How to show the bashdb console
How to show the bashdb console

Please note, that BashSupport may interfere with your input.
Also, your input may interfere with the debugger functionality.

The bashdb console in BashSupport Pro
The bashdb console in BashSupport Pro

bats-core Tests with BashSupport Pro

Introduction

bats-core is a well–known and widely used software to define and run automated tests for shell and Bash scripts. You can learn more about it at https://github.com/bats-core/bats-core.

bats-core files have the file extension .bats. They are highlighted like .bash files.

Supported System Configurations

All versions of GNU Bash, version 3 and later, are supported.

macOS, Linux, and Windows are supported. On Windows bats-core tests can be run with Bash installed WSL, Git Bash, or Cygwin.

Limitations

  • debugging bats-core tests isn’t possible yet
  • .bats files are not fully compatible with Bash syntax. Errors may show up in these files, especially if BashSupport Pro is used together with the open–source BashSupport plugin.

Here are some extensions you could use in your bats-core tests:

How To Create bats-core Files

Files with the extension .bats are displayed with a little bat icon to tell that it’s a bats–core file. BashSupport Pro comes with a basic template for bats–core tests.

If you don’t like the guided steps below, just create a file with this extension as you’re used to.

BashSupport Pro supports you to manage bats-core files:

  1. First, choose FileNew from the main menu.
    How to create a new bats-core file in BashSupport Pro
    How to create a new bats-core file in BashSupport Pro
  2. Click on the item bats-core Test. A new dialog pops up.
  3. Now enter the name of the new bats-core file and confirm by Enter . The file extension .bats is automatically appended if you don’t enter it.
    Defining the name of a new bats-core file
    Defining the name of a new bats-core file
  4. BashSupport Pro now creates the new file and opens an editor to show it. The file already contains a simple test setup to run your first test.
    A new bats-core file created by BashSupport Pro
    A new bats-core file created by BashSupport Pro

How To Edit bats-core Files

.bats files are edited as regular Bash files.

Live Templates

You can use the live templates feature to quickly create new test functions in a file. The following sections list the available live templates and explain how to use them.

@test
A line, which starts with @test, defines a new bats–core test.
  1. Enter @test
  2. Press the TAB key to insert a new test function into the file.
  3. The editor first asks for the description of the new test. Enter a value, e.g. my name, and press Enter .
  4. The caret now moves into the body of the function and now allows you to implement your new test.
1
2
3
@test "my name" {
    # ← caret is put here
}
setup
The function setup is executed before each test function, if it’s defined.
  1. Enter setup
  2. Press the TAB key to insert a new setup function into your file. Your new function now looks like this:
1
2
3
4
# executed before each test
setup() {
    # ← caret is put here
}
teardown
The function teardown is executed after each test function, if it’s defined.
  1. Enter teardown
  2. Press the TAB key to insert a new teardown function into your file. Your new function now looks like this:
1
2
3
4
# executed after each test
teardown() {
    # ← caret is put here        
}

Limitations

  • Formatting bats-core files isn’t fully supported yet
  • Debugging bats-core files isn’t possible yet

Running bats-core Tests

There are several ways to run bats-core tests:

  • all tests in a directory
  • all tests in a file
  • a specific test in a file

How To Run All Tests in a Directory

Choose Run ‘All tests’ in the context menu on the directory. This creates a new bats-core run configuration to execute all tests in all .bats files in this directory and all sub directories.

How To Run All Tests in a File

Click on the first green arrow gutter icon in the file and choose All tests in the context menu. This creates and runs a new bats-core run configuration for the current file.

How To Run a Specific Test

Click on the green arrow gutter icon in the file and choose Run ‘your test name’ in the context menu. This creates and runs a new bats-core run configuration for only this function.

bats-core Run Configurations

bats-core tests are run via “Run Configurations”, which is a feature of your JetBrains IDE. Please refer to JetBrains’s help to learn more about it.

Properties

You can configure these properties for bats-core run configurations. They correspond to the available command line options of bats-core.

Test data path
The file to a .bats file or a directory, which contains .bats files.
Test name pattern
A regular expression to define the tests, which should be executed in the source defined by Test data path .
Recursive
If this is enabled and Test data path points to a directory, then .bats files will be searched recursively in the directory and all sub directories. Disable this if you only want to limit the test search to just the directory you specified.
Number of parallel jobs
This defines how many tests are run in parallel. The GNU parallel command has to be installed to use this feature.
Interpreter path
This defines the shell to run the bats-core test runner. bats-core is a Bash script and needs an interpreter to run. By default BashSupport Pro lets your operating system choose the interpreter. Because this isn’t possible on Windows, the plugin tries to automatically locate an installation of Bash.
Use this property to specify your own path to the Bash interpreter to use.
Program arguments
The arguments to pass to the bats-core test runner. This shouldn’t be needed, but still allows you to pass special flags if you’re doing something special here.
Working directory
The working directory for the bats-core test runner. By default it’s the directory of your test data path.
Environment variables
This allows you to define the environment variables of your test runner. For example, it’s possible that some tests expect a specific environment. This allows you to define this.

bats-core Test Result

You’ll see the test results after you executed one ore more bats–core tests. BashSupport Pro helps you to navigate in these results.

Tests are grouped by the files, in which they are defined.

Working With Files

Navigate to bats-core file from the test runner results
Navigate to bats-core file from the test runner results

The context menu allows you navigate to the file, which is selected in the test results. It also allows you to run all tests of only the selected file. This is especially useful when you were running many tests in a directory. Alternatively you can choose to create, but not run, a bats-core configuration for the chosen file.

Working With Tests

Navigate to a specific bats-core test from the test runner results
Navigate to a specific bats-core test from the test runner results

The context menu on a test item allows you to navigate to this particular test. It also allows you to run only the selected test function. This is especially useful when you’re debugging a failing test, for example. Alternatively you can choose to create, but not run, a bats-core configuration for the chosen test function.

Navigate to the cause of an error message
Navigate to the cause of an error message

Error messages, which are generated by bats-core, contain filename and line number where the error occurred. BashSupport Pro highlights the filename of these errors. Just click on the link to navigate to the line, where the error occurred.