asdf core contribution guide.

Initial Setup

Fork asdf on GitHub and/or Git clone the default branch:

# clone your fork
git clone<GITHUB_USER>/asdf.git
# or clone asdf
git clone

The tools for core development are in this repo's .tool-versions. If you wish to manage with asdf itself, add the plugins:

asdf plugin add bats
asdf plugin add shellcheck
asdf plugin add shfmt

Install the versions to develop asdf with:

asdf install

It may be useful to not use asdf to manage the tools during development on your local machine as you may need to break functionality which would then break your dev tooling. Here's the raw list of tools:


If you want to try out your changes without making change to your installed asdf, you can set the $ASDF_DIR variable to the path where you cloned the repository, and temporarily prepend the bin and shims directory of the directory to your path.

It is best to format, lint and test your code locally before you commit or push to the remote. Use the following scripts/commands:

# Lint
./scripts/lint.bash --check

# Fix & Format
./scripts/lint.bash --fix

# Test: all tests

# Test: for specific command
bats test/list_commands.bash


Add tests! - Tests are required for new features and speed up review of bug fixes. Please cover new code paths before you create a Pull Request. See bats-core documentationopen in new window


The following is the .gitignore file in the asdf-vm/asdf repository. We ignore project-specific files. Files specific to your OS, tools or workflows should be ignored in your global .gitignore configuration, see hereopen in new window for more details.



asdf uses a .git-blame-ignore-revs to reduce noise when running a blame. See the git blame documentationopen in new window for more information.

Use the file with git blame like so:

git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats

Optionally, configure to use the file on every invocation of blame without manually supplying it:

git config blame.ignoreRevsFile .git-blame-ignore-revs

It is possible to configure IDEs to use this file. For example, when using VSCode (with GitLensopen in new window), write the following to .vscode/settings.json:

  "gitlens.advanced.blame.customArguments": [

Bats Testing

Execute tests locally with:


Before writing tests please read:

Bats Tips

Bats debugging can be difficult at times. Using the TAP output with -t flag will enable you to print outputs with the special file descriptor >&3 during test execution, simplifying debugging. As an example:

# test/some_tests.bats

printf "%s\n" "Will not be printed during bats test/some_tests.bats"
printf "%s\n" "Will be printed during bats -t test/some_tests.bats" >&3

This is further documented in bats-core Printing to the Terminalopen in new window.

Pull Requests, Releases & Conventional Commits

asdf is using an automated release tool called Release Pleaseopen in new window to automatically bump the SemVeropen in new window version and generate the Changelogopen in new window. This information is determined by reading the commit history since the last release.

Conventional Commit messagesopen in new window define the format of the Pull Request Title which becomes the commit message format on the default branch. This is enforced with GitHub Action amannn/action-semantic-pull-requestopen in new window.

Conventional Commit follows this format:

<type>[optional scope][optional !]: <description>

<!-- examples -->
fix: some fix
feat: a new feature
docs: some documentation update
docs(website): some change for the website
feat!: feature with breaking change

The full list of <types> are: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.

  • !: indicates a breaking change
  • fix: will create a new SemVer patch
  • feat: will create a new SemVer minor
  • <type>!: will create a new SemVer major

The Pull Request Title must follow this format.


Use Conventional Commit message format for your Pull Request Title.

Docker Images

The asdf-alpineopen in new window and asdf-ubuntuopen in new window projects are an ongoing effort to provide Dockerized images of some asdf tools. You can use these docker images as base for your development servers, or for running your production apps.