BashSupport Pro adds advanced features for shell scripts to your IDE.
Debug Bash scripts, run bats-core tests, navigate with ease, 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

Download BashSupport Pro

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

You can download every version of BashSupport Pro on the marketplace: Download.

Features of BashSupport Pro

BashSupport Pro is under active development. The list of features will grow in the future.

A detailed comparison of BashSupport Pro, JetBrains Shell and legacy BashSupport is available here: Plugin Comparison.

What BashSupport Pro Adds To Your IDE

Feature
Debugger
bashdb integration for Bash v4 and v5 on macOS, Linux, Windows.  more
Test Runner
Fully features bats–core test runner.  more
ShellCheck Support
Displays ShellCheck’s messages in the editor.
shfmt Formatter
Format files using shfmt.
Powerful Run Configurations
Inline snippets, Windows path mapping (WSL, Cygwin, Git Bash), input and output redirection.
Legacy Run Configurations
Supports run configurations of legacy BashSupport and of the JetBrains Shell plugin for a smooth migration.
Code Completion
For functions, variables references, variable declarations, file paths and built-in names.
Highlighting
Syntax highlighting. Advanced highlighting of local variables and reassigned local variables.  more
Multi-File Navigation
For functions, variables references, and variable declarations. Supports sourced files.
Find Usages
For functions, variables references, and variable declarations. Supports sourced files.
Rename Refactoring
Rename functions and variable definitions and all usages, across multiple files.
Quick Documentation
Quick documentation of functions, variables, and Bash commands.  more
Code Folding / Custom Code Folding
Folding for grouping elements and Vim-style {{{...}}}.  more
Spellcheck: Common dictionaries
Bundled dictionaries with common Bash, GNU, and POSIX commands.  more
source Command Support
Go to declaration, updates file references after rename and move operations.
Go To Symbol
Available for function and variable definitions.
New File Action
Smart new file action.  more
Basic Intentions
quote, unquote, escape, unescape.  more
Basic Inspections (Beta)
Highlight variables, which may be declared as local. Highlight unresolved variables.  more

Pricing — Subscription With a Fallback License

Fallback License means a perpetual license after 12 months of payment.

Types of Licenses

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

Here’s an overview. You could also check JetBrains’ comparison chart and JetBrains’ 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.

Introduction to BashSupport Pro

BashSupport Pro is a plugin to provide a complete Bash editing environment.

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.

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 mail@bashsupport.com or by using the online form at plugin-dev.com.

Free License for Educational and Open–Source Use

Please refer to the pricing page to find out if you’re eligible for a free educational or open–source license.

Free License For All Contributors To Legacy BashSupport

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 resources.
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.
licensed
Example: true
Boolean value if a license is found for the plugin.
trial
Example: true
Boolean value if the current license is for trial.
trial_days
Example: 28
Number of remaining days if the current license is for a trial

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
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
config_type (example: “LegacyShRunConfiguration”)
Type of the executed run configuration
interpreter_type (example: “automatic”)
The selected default interpreter type
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
quickfixFired when a quickfix of BashSupport Pro was applied in a file
Properties
quickfix_name (example: “CreateShellcheckSourceDirective”)
The ID of the applied quickfix
run_config_startedFired when a run configuration is executed
Properties
file_ext (example: “sh”)
File extension of the debugged file
type (example: “window”)
Type of the execution target: window or terminal
config_type (example: “LegacyShRunConfiguration”)
Type of the executed run configuration
interpreter_type (example: “automatic”)
The selected default interpreter type
charset (example: “UTF-8”)
The charset used to parse the output
statusAggregated numbers of often used features
Properties
status_c (example: “10”)
Number how often code completion was requested, this is the sum of the other completion values
status_c_var (example: “10”)
Number how often code completion of variables was requested
status_c_def (example: “10”)
Number how often code completion of variable definition was requested
status_c_cmd (example: “10”)
Number how often code completion of command names was requested
status_doc (example: “10”)
Number how often code quick documentation was shown
status_doc_bash (example: “10”)
Number how often code quick documentation of a Bash command was shown
status_doc_script (example: “10”)
Number how often code quick documentation of script elements was shown
status_file_posix (example: “10”)
Number how often a POSIX .sh file was opened or activated
status_file_bash (example: “10”)
Number how often a Bash file was opened or activated
status_file_scratch (example: “10”)
Number how often a Shell/Bash scratch file was opened or activated
trial_end_notificationFired when a notification was shown, which informs trial users that the trial expires soon.
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: github.com/BashSupport-Pro/bats-core/tree/bashsupport-pro.
ShellCheck (standalone software, bundled)
© 2012-2020 Vidar ‘koala_man’ Holen and contributors.
GNU General Public License v3.0
ShellCheck is an immensely powerful software to locate and fix issues with your shell scripts. ShellCheck binaries, sources, and license are bundled with BashSupport Pro. The binaries are build from the unmodified sources.
The source repository for the builds is github.com/BashSupport-Pro/shellcheck
shfmt (standalone software, bundled)
© 2016-2020, Daniel Martí. All rights reserved.
BSD 3-clause License
shfmt is part of a wonderful, powerful toolset to work with Shell scripts. shfmt binaries are bundled with BashSupport Pro. The binaries are build from the unmodified sources.
The source repository for the builds is github.com/BashSupport-Pro/sh.
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: github.com/BashSupport-Pro/pty4j.
intellij-makefile (plugin, not bundled)
© 2016 Victor Kropp
MIT License
intellij-makefile is a great plugin, which adds support for Makefiles to your IDE. BashSupport is using code of intellij-makefile to highlight shell code in Makefiles.
The license and copyright notice is bundled with each download of BashSupport Pro.

How To Install BashSupport Pro

  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. Open the plugin settings File > Settings... > Plugins
  3. Enter BashSupport Pro in the text input field to quickly locate it.
    BashSupport Pro on the JetBrains Marketplace
    BashSupport Pro on the JetBrains Marketplace
  4. Click the Install button to download it
  5. Restart your IDE
  6. BashSupport Pro is a standalone plugin. It’ll ask you to deactivate conflicting plugins, i.e. JetBrains Shell or the legacy BashSupport plugin.

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

Go To Declaration

BashSupport Pro helps you to quickly navigate in shell scripts.

Place the text cursor on an element in a shell script and choose NavigateGoTo to navigate to the declaration (JetBrains help pages).

BashSupport Pro lets you navigate to the declarations of these elements:

Function Calls
It navigates to the definition of the function.
Variable References
It navigates to the definition of the variable. For example, it navigates to export myVar if you invoke it for $myVar.
Variable Declarations
It navigates to the closest, earlier declaration of a variable declaration.
For example, for myVar=1; myVar=2; export myVar, it will navigate to myVar=2 if you call it for the exported definition. When you invoke the action again, then it will navigate to myVar=1.
See below for a setting to configure this behaviour.

Settings

By default, Go To Declaration navigates to the closest re-declaration of a variable. This should be the most useful implementation to navigate within complex shell scripts. If you don’t like this, then the setting Prefer the closest definition for Go To Declaration lets you change the behaviour. To do this, disable the checkbox in the settings at SettingsLanguages & FrameworksBashSupport Pro .

Local Scope

BashSupport Pro supports the local variable scope. local allows to restrict the visibility of variables to the current function. It’s only available for Bash scripts, i.e. it’s not available in POSIX scripts.

Go To supports local scope. If you call it within a function, then it’ll only navigate to the local declarations. If you call it outside of a function, then it’ll ignore variables, which were declared as local.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
myVar=1

myFunction() {
    # will NOT navigate to the global declaration
    local myVar="local value" 
    
    # navigates to the local definition above
    printf "$myVar"
}

# navigates to myVar=1, skips the local declaration
echo $myVar 

Unset

BashSupport Pro supports the unset command. unset allows you to make a variable unavailable to all following commands. The plugin considers variables, which have been unset as a new variable.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
a=1
echo $a
# 'Go To Declaration' on a
# navigates to a=1
# Rename will rename this a and previous occurrences 
unset a

# $a is unresolved here, 
# because it was unset 
echo $a

# 'Go To Declaration' on a 
# will not navigate to previous declarations
# because it was unset.
# Rename will only rename this a and the line below
a=2
echo $a

Scratch Files

BashSupport Pro allows you to navigate in scratch files. The complete feature–set is available, but limited to the current file.

Injected Code

BashSupport Pro allows you to navigate in code with language injection. The complete feature–set is available, but limited to the code block. Navigation between multiple blocks is not yet supported.

Find Usages

EditFind Usages… allows you to locate usages of the current definition. This is useful to find out where a function is called or where a variable is referenced in your scripts.

Introduction

BashSupport Pro supports the source command and follows sourced files.

Source Command Support

If you use the command with relative paths, then the plugin will automatically follow these files.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
## a.bash

# Call 'Go To Declaration' on the filename to open it.
# BashSupport Pro uses declarations in lib.bash for:
#  code completion
# - go to declaration
# - find usages
# - rename
# - quick documentation

source ./lib.bash

# Renaming 'myFunc' here
# also renames it in lib.bash 
myFunc
1
2
3
4
5
6
7
## lib.bash, sourced by a.bash

# Renaming 'myFunc' here
# also renames it in a.bash 
myFunc() {
    echo hello world
}

Shellcheck Support

If you’re using dynamic values with the source command, then BashSupport Pro needs help to locate the file.

For example, code like this is commonly used:

1
. "${_basedir}/included-file.sh"

$_basedir is only known at runtime and BashSupport Pro needs help here.

Define a shellcheck source directive to tell BashSupport Pro where to find the sourced file:

1
2
3
4
# hint for BashSupport Pro where to find the file
# 'Go To Declaration' on the filename opens it
# shellcheck source=./lib/included-file.sh
. "${_basedir}/included-file.sh"

Now Go To, Find Usages, Rename, etc. will also take care of the elements in the sourced file.

Go To Declaration

BashSupport Pro supports two scenarios:

  1. The declaration is in a sourced file
  2. The declaration is in a file, which sources the current file

Code Completion

Code completion works across multiple files.

Rename Refactoring

Rename works across multiple files. Everything, which is located by Find Usages is also renamed by this refactoring.

Go to Symbol

BashSupport Pro implements NavigateSymbol… This feature is available with 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.

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 assigns the following file extensions and file names to the plugin.

File Extensions

  • *.sh
  • *.bash
  • *.zsh
  • *.bats: this is assigned to the bats–core test runner integration.
  • Files without extension, but with a hash bang line like #!/bin/sh

File Names

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

Quick Documentation

BashSupport Pro supports the quick documentation feature for variables, variable declarations, functions and commands.

Variables

Documentation of a Bash variable
Documentation of a Bash variable

All previous modifications of type and properties are tracked. This tracking until there’s no more declaration or until the the variable is unset.

Line comments, which immediately precede the first declaration, are displayed as documentation of that variable.

Supported types:

  • String, this is the default and not displayed
  • Array, e.g. by declare -a
  • Associative Array, e.g. by declare -A
  • Number, e.g. by declare -i

Supported properties:

  • Scope (Global or Local)
  • Read–only, e.g. by readonly
  • Exported, e.g. by export

Variable Declarations

The documentation of variable declarations is similar to variables. Properties and type are first taken from the declaration itself and then merged with any previous declaration of the same variable.

Line comments, which immediately precede the first declaration, are displayed as documentation of that variable.

Functions

Documentation of a function
Documentation of a function

Quick documentation is available on the function name itself or on any invocation of that function.

Line comments, which immediately precede the declaration of the function, are displayed as documentation of that variable.

If the first comment follows the form name(param1,param2), then the parameters are displayed in the rendering.

Commands

Documentation of a Bash built-in command
Documentation of a Bash built-in command

For Bash’s built-in commands, BashSupport Pro displays the content returned by the help command for that particular command.

For other commands, BashSupport Pro displays the info page.

Formatter Support

BashSupport Pro supports shfmt to format your shell scripts.

Code Style Settings

Code Style Settings for the shfmt Formatter
Code Style Settings for the shfmt Formatter

Settings

BashSupport Pro bundles shfmt binaries for macOS, Linux and Windows. If you want to use a locally installed version of shfmt, then you can set your own path at Settings…Languages & FrameworksBashSupport Pro .

How to set a custom path to shfmt
How to set a custom path to shfmt

Limitations

The following settings are not yet supported:

  • formatting only the selected text of a file

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.

Inspections Of BashSupport Pro

You can click on the screenshots to learn more about this particular inspection. Additionally, ShellCheck is executed to highlight the most common problems of your scripts: ShellCheck integration.

This inspection highlights variables, which could be declared as local.

The message is displayed under these conditions:

  1. The current is a .bash file.
    The local keyword is not available in POSIX shell scripts.
  2. The declaration is inside of a function
  3. All references to the declaration are in that function.
    References outside of it or sourced files inside of the function prevent it from being declared as local.

Quick Fix

There’s no quick fix yet—it’ll be added as soon as possible.

This inspection highlights file references, which are not found on disk. It’s available for file path arguments of the source and . commands.

Quick Fix

There’s no quick fix yet—it’ll be added as soon as possible.

This inspection highlights modifications of variables, which were declared as read–only.

It highlights a modification under these conditions:

  1. It was previously declared as read–only. For example, readonly and declare -r declare a variable as read–only.
  2. It’s an assignment or modification. myVar=value is a modification, export myVar is not a modification.

This inspection highlights file path arguments to the source command, which are not constant.

Quick Fix

Use the available quickfix to quickly create a shellcheck source= comment.

If only one file with the defined name exists in your project, then it’s automatically referenced.

If more than one file exists, then a popup is shown to let you pick the right one.

This inspection highlights local variables, which are not referenced. It’s highlighted as an unused symbol, to let you quickly see that it’s not used.

The message is displayed under these conditions:

  1. The variable is declared as local in a function
  2. It’s the first declaration of that variable in that function
  3. It’s not exported and there are no references to that variable in the function

Quick Fix

There’s no quick fix yet—it’ll be added as soon as possible.

This inspection highlights unresolved variables.

It’s disabled by default, because it’s still in beta status. You can enable it via Settings…EditorInspectionsBashSupport ProUnresolved variable (BETA) .

A variable is highlighted as unresolved under these conditions:

  • it’s not previously declared in the file
  • it’s not a built–in or predefined variable. For example $PATH is a built-in variable and $HOME is a predefined variable.

The validation is currently not good–enough to enable this inspection by default. For example, conditional statements are not checked at this time.

Intentions Of BashSupport Pro

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.

Shellcheck Support

Error Highlighting

BashSupport integrates ShellCheck’s warnings and error messages into the editor.

Settings

BashSupport Pro bundles ShellCheck binaries for macOS, Linux and Windows. If you want to use a locally installed version of ShellCheck, then you can set your own path at Settings…Languages & FrameworksBashSupport Pro .

How to set a custom path to ShellCheck
How to set a custom path to ShellCheck

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.

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.

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 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.

Run Configurations

BashSupport Pro supports three types of run configurations.

  1. BashSupport Pro . This is BashSupport Pro’s default and should be used for new configurations.
  2. Legacy BashSupport : compatibility with run configurations created with the legacy BashSupport plugin.
  3. JetBrains Shell Script : compatibility with run configurations created with the JetBrains Shell plugin.

The file formats of the legacy run configurations are fully supported for reading and writing.

How to Execute a Shell Script File

This works in the same way as with almost every other file in your IDE.

Line Marker

A marker on the first line of shell scripts allows you to quickly execute a script. You can also use it to quickly create a run configuration.

The default interpreter for the type of the current file is used to execute it. You can configure the interpreters in the application settings.

Run in terminal
This opens a new tab in the terminal tool window and executes the script. This is useful if you want to run it in the terminal without creating a run configuration for it.
Run demo.bash
This executes the script as a run configuration. This is most likely what you’re used to from all the other plugins in your IDE.
Debug demo.bash
This executes the script in the built-in debugger. It’ll create a new, temporary run configuration if there’s no one yet for the current file.
Create/Edit demo.bash
Create is shown if there’s no run configuration yet for the current file. Click the menu item to open a dialog to edit the settings of the new configuration.
Edit is shown if there is an existing run configuration. Click the menu item to open a dialog to modify the settings.

Add Your Favourites

You can add your favourite, or most–often used interpreters to the menu to quickly launch scripts with that particular interpreter. Enable the settings Show in menu in the application settings for those interpreters, which should be displayed in this menu.`

Context Menu

The context menu of shell script files is another way to quickly execute the file. The items Run , Debug , Create , and Edit work exactly the same way as in line marker menu at the first line of the file.

How to Execute a Shell Script Snippet

A powerful feature of BashSupport Pro’s run configuration is the support for inline snippet. You can define a small shell script in the run configuration without having to store it somewhere in the file system.

To define a snippet:

  1. Create an empty run configuration of type BashSupport Pro, e.g. via RunEdit Configurations…BashSupport Pro
  2. Choose Inline Snippet as the source of the run configuration
  3. Enter the snippet in the editor below

Example: Choose and Open a File

The screenshot above displays a run configuration to quickly open a file with your operating system’s default handler. This example won’t work on Windows, though.

  1. Choose Snippet as the run configuration’s source.
  2. Define the snippet in the editor below. Code completions and many other features are available in this context.
  3. In our example the snippet is
    1
    2
    
    echo "Opening $1"
    xdg-open "$1"  
    
  4. Insert the macro $FilePrompt$ into the script argument field. The plus–sign on the right allows you to browse all available macros. The IDE evaluates macros before the run configuration is executed. So it’ll first prompt you to select a file and then passes the chosen path to the script as an argument.

Using Run Configurations of Legacy BashSupport

If you used the legacy BashSupport plugin in the past, then you’ll most likely have a bunch of run configurations in your projects. BashSupport Pro fully supports these run configurations. The user interface is different from the old plugin, but the storage format on disk is the same as defined by legacy BashSupport. You can safely modify the settings and continue to share the run configuration with others, who don’t use BashSupport Pro yet.

Possible Incompatibilities

Data Format

All compatible settings are stored in the format of the legacy plugin. New settings, which are only supported by BashSupport Pro, are stored in BashSupport Pro’s format. For example, you can define Redirect input from . But because the old plugin didn’t support it, it will only be useful for others if they have BashSupport Pro installed, too.

Default Interpreter

Legacy BashSupport has a setting Use Project Interpreter . This setting will be mapped to Interpreter: Default interpreter for script . The configured interpreters of these settings may be different, of course. To achieve identical results, please make sure that both settings point to the same interpreter on your machine.

Using Run Configurations of the JetBrains Shell Plugin

BashSupport Pro fully supports the run configurations of the JetBrains Shell plugin. The user interface is different, because it supports additional features. But the storage format on disk is the same as defined by the Shell plugin. You can safely modify the settings and continue to share the run configuration with others, who don’t use BashSupport Pro yet.

Possible Incompatibilities

Data Format

All compatible settings are stored in the format of the Shell plugin. New settings, which are only supported by BashSupport Pro, are stored in BashSupport Pro’s format. For example, you can define Redirect input from . But because the old plugin didn’t support it, it will only be useful for others if they have BashSupport Pro installed, too.

Interpreter Path

The Shell plugin does not allow you to define a default interpreter. The path to the interpreter is always stored in the run configuration. This makes it difficult to share run configurations between developers, who use different operating systems or different setups.

BashSupport Pro uses the configured path by default. If you’d like to make a run configuration easier to share, you can change the interpreter to one of the default interpreters. Please note that this is only useful if everyone on your team has BashSupport Pro installed. Alternative, leave the config alone and create a new run configuration of type BashSupport Pro .

Run Configuration Settings

Configuration

Most of the following fields support macros. The little plus-sign on the right guides you which macros are available for a particular property.

Here’s JetBrains help page about run configurations: Run/debug configurations.

Source
Defines the script to execute. You can choose between File and Inline Snippet .
  • File: The file path to the script, which should be executed. Learn more
  • Inline Snippet: Store a snippet inside of the run configuration without creating a new shell script on disk. This is usually useful for small utilities or scripts to automate things in your workflow. Learn more
Script arguments
This allows you to pass arguments to the script. This is supported for both file and inline snippet sources. Wrap an argument with double-quotes if it contains spaces, e.g. "first argument" second.
Working directory
This allows you to customize the working directory of your script. The default value is displayed if there’s no custom value set.
Environment variables
This allows you to customize the environment of your script. You can add items in the form key=value. By default, the parent environment is passed. Use the little icon on the right to customize this behaviour.
Interpreter
This allows you to customize the interpreter, which is used to execute your script. The default interpreters are configured in your application settings at FileSettingsLanguages & FrameworksBashSupport Pro .
Default interpreter for script
The type of your script defines, which default interpreter is used. The POSIX interpreter is used for.sh files and the Bash interpreter is used for .bash files, for example.
Default Bash interpreter
The first interpreter with type Bash is picked from the list of configured interpreters.
Default POSIX interpreter
The first interpreter with type POSIX is picked from the list of configured interpreters.
Default zsh interpreter
The first interpreter with type Zsh is picked from the list of configured interpreters.
Chosen by your OS
On Linux and macOS files can be made executable. With this setting your operating system will pick the interpreter for you, if there’s one. This is useful to avoid side–effects by your own interpreter settings. You could also use this to run regular executables, which are not shell scripts.
Custom interpreter path
Finally, this allows you to set your own interpreter for just this run configuration. Please note that this might cause compatibility issues if you share such run configurations with members of your team.
Windows path mapping
This property allows you to define how the script path is mapped on Windows. Paths like C:\dir\file.txt are not valid UNIX paths and need to be mapped to something like /mnt/c/dir/file.txt. WSL, MSYS, and Cygwin all have different mapping strategies and this property allows to configure which mapping should be used, if the automatic detection failed to do the right thing.
Redirect input
This is stdin redirection. This allows you to choose a file, which will be send to stdin of your executed script. Please note, that ANSI escape codes will not be interpreter in your scripts output if this is defined, because stdin redirection turns of the console emulation.

Logs

This is the same log configuration, which you might have already used with other types of run configurations. The table at the top allows you to define log files, which should be opened when you execute this run configuration.

Save console output to file lets you save the content of stdout to a file on disk.

Startup/Connection

This setting is only useful for debugging, when the automatic detection of the version of your Bash interpreter failed. This should only rarely be needed. If you don’t know what to do here, set this to Automatic .

Application Settings

The application settings allow you to define a list of default shell interpreters.

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 separate 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.