Shellform

Shell Script Formatter for Visual Studio Code

Shellform is a lightweight Visual Studio Code extension for formatting shell scripts using shfmt.

0.3.0 adds formatting cancellation and formatter-process cleanup. It provides whole-document formatting through VS Code, using the current editor buffer and the document's indentation options. Behaviour may change as the extension develops.

📦 Installation

Requirements:

• Visual Studio Code 1.101.0 or later.
• An externally installed shfmt executable available on the extension host's PATH. Shellform does not bundle or download it.

Install shfmt using the instructions in the shfmt project, then verify your installation:

shfmt --version

Install Shellform from the Visual Studio Marketplace.

For WSL, Remote SSH, or development containers, install both Shellform and shfmt in the remote environment where the workspace extension host runs.

🚀 Quick Start

1. Open a shell script, or create an untitled document.
2. Set its language mode to Shell Script if it is not already selected.
3. Run Format Document With... and select Shellform.

For example, with four-space indentation:

if true; then
echo hello
fi

Becomes:

if true; then
    echo hello
fi

To use Shellform as the default shell formatter and format on save, add this to your VS Code settings:

{
    "[shellscript]": {
        "editor.defaultFormatter": "crisvsgame.shellform",
        "editor.formatOnSave": true
    }
}

🔧 Features

• Whole-document formatting through VS Code's formatting provider.
• Current in-memory input, including unsaved changes and untitled documents.
• Eligibility based on Shell Script language mode, with no filename-extension requirement.
• Tabs or spaces and indentation width taken from VS Code's formatting options.
• No edits for unchanged formatter output.
• No edits for cancelled formatting requests.
• Formatter input cleanup and active-process termination requests on cancellation or failure.
• No edits after process or stream failure, unsuccessful exit, or a document-version change.
• Formatted edits applied by VS Code; Shellform does not write the source file directly.
• Script contents passed to shfmt as data, never executed.
• No runtime npm dependencies.

🎛️ Formatting Behaviour

Configure indentation through VS Code:

{
    "[shellscript]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 4
    }
}

Shellform passes the buffer to shfmt through stdin and reads the formatted result from stdout. It supplies -i for indentation and otherwise uses the installed formatter's defaults. There are no Shellform-specific settings or free-form argument options in this release.

🚧 Current Limitations

• Whole-document formatting only; selection/range formatting is not implemented.
• Shellform does not yet select or enforce a shell dialect; shfmt's automatic dialect detection and fallback behaviour apply.
• Shellform does not provide EditorConfig integration. Its explicit indentation flag disables shfmt's EditorConfig formatting options.
• Timeouts, automatic request supersession, and active-process cleanup on extension deactivation are not yet implemented. A stalled formatter can leave a request pending unless the request is cancelled.
• Failures are logged to the extension host console; there are no user-facing error notifications or executable-path settings yet.
• Development has been exercised in WSL Ubuntu. Windows, macOS, and other remote environments have not been validated.

📂 Project Structure

src/
    extension.ts
    format-provider.ts
    format-request.ts
    test/
        extension.test.ts
test/
    lifecycle.test.cjs
images/
    icon.png
    icon.svg
.vscode/
    launch.json
    tasks.json
.vscode-test.mjs
.gitignore
LICENSE
CHANGELOG.md
README.md
package-lock.json
package.json
tsconfig.json
out/ # generated JavaScript and source maps

🧪 Testing

Install development dependencies and run the tests:

npm ci
npm test
npm run test:lifecycle

The lifecycle command compiles the extension and runs 20 tests with mocked processes and VS Code objects. They cover cancellation, cleanup, late events, stale and unchanged results, and overlapping requests. No running VS Code host or installed shfmt is needed for this suite.

The integration command compiles the extension and runs tests in a downloaded VS Code Extension Development Host. It requires shfmt on PATH and a graphical environment capable of running VS Code.

The current configuration targets stable VS Code. Four integration tests cover spaces, tabs, unchanged input, and invalid shell syntax through VS Code's formatting API. A fifth checks that VS Code cancels a pending formatting token when the document changes during the normal Format Document action.

After building, run against the minimum supported VS Code version:

npm exec -- vscode-test --code-version 1.101.0

🛠️ Build

Build the extension:

npm run build

Watch for source changes:

npm run dev

Open the repository in VS Code and press F5 to launch the configured Extension Development Host.

📝 License

MIT License

🔗 Links

• Marketplace: https://marketplace.visualstudio.com/items?itemName=crisvsgame.shellform
• Source Code: https://github.com/CRISvsGAME/shellform
• Issues: https://github.com/CRISvsGAME/shellform/issues
• shfmt: https://github.com/mvdan/sh