This repository provides the user-wide PowerShell command Format-Ahk. It wraps the formatter from the AutoHotkey v2 Language Support extension. This project was developed with assistance from OpenAI Codex.

AutoHotkey files must use UTF-8. When writing files, the command uses UTF-8 without a BOM and LF line endings.

Formatter settings are read from the AutoHotkey2.FormatOptions object in a JSON file. See example/config.json for a complete example. The companion VS Code extension can copy that object into VS Code settings.

• PowerShell 7
• Node.js
• Git and npm for installation

Windows PowerShell, included with Windows, is version 5 and is not supported.

Run the installer from the repository root:

pwsh -File .\tool\Install-AhkFormatter.ps1

The installer copies the module to the first user-owned directory in $env:PSModulePath. It also downloads, patches, and builds a pinned formatter revision under the current user's local application-data directory.

Open a new PowerShell 7 session after installation. After updating this repository, update the installed module and formatter with:

pwsh -File .\tool\Install-AhkFormatter.ps1 -Update

Always provide the project's formatter configuration:

# Return formatted text
Format-Ahk .\source.ahk -Config .\config.json

# Return a result object that includes the formatted text
Format-Ahk .\source.ahk -Config .\config.json -PassThru

# Format files in place
Format-Ahk . -Config .\config.json -Write

# Check formatting and fail if any file would change
Format-Ahk . -Config .\config.json -Check -FailOnChange

Paths may identify files, directories, or wildcards. Directories are searched recursively for .ahk, .ah2, and .ahk2 files.

The test suite includes an end-to-end test and requires the formatter to be installed. Install Pester 5, then run the suite with PowerShell 7:

Install-PSResource -Name Pester -Version 5.9.0 -Scope CurrentUser
pwsh -File .\tool\Tests\Invoke-Tests.ps1

Install the remaining development tools:

Install-PSResource -Name PSScriptAnalyzer -Version 1.25.0 -Scope CurrentUser
npm install --global markdownlint-cli2

Enable the repository hooks once per clone:

git config core.hooksPath .githooks/hooks

Pre-commit checks staged files, commit-msg validates the message, and pre-push checks committed HEAD and runs the formatter and extension tests. See .githooks/README.md for details.

The companion extension copies AutoHotkey2.FormatOptions from a configurable JSON or JSONC file into another file without changing unrelated settings.

Install the prebuilt VSIX:

code --install-extension .\extension\ahk-format-config-0.1.0.vsix

Open example/ as a VS Code workspace to try automatic export. See extension/README.md for settings, manual export, and development commands.

The formatter comes from the AutoHotkey v2 Language Support repository. Its pinned revision is recorded in AhkFormatter.psd1.

The installer applies one patch to preserve JSON string, number, and boolean values and another to remove trailing whitespace from blank JSDoc lines. The patches modify LGPL-3.0-licensed upstream code and use the same license; see tool/Patches/LICENSE.