Repository files navigation

toolset is a lightweight utility for managing project-specific tools like linters, formatters, and code generators. Itensures that your development tools remain up-to-date and allows you to specify exact tool versions for consistent,reproducible builds.

• Centralized Tool Management: Easily manage and update tools like linters, formatters, and code generators withinyour project.
• Reproducible Builds: Ensure consistent results by locking tool versions in your project configuration.
• Automatic Updates: Keep your tools up-to-date with a single command, avoiding manual version checks and upgrades.
• Multiple Runtimes: Support for both Go builds and GitHub releases. Use thegh runtime to install pre-builtbinaries from GitHub releases (like golangci-lint) for significantly faster installation compared to building fromsource.

When developing software, you often rely on various tools—such as linters, formatters, and test runners—that arecritical for maintaining code quality. These tools are frequently updated with new features or fixes. To maintainstability and ensure that everyone working on the project uses the same toolset, you need a way to lock in specific toolversions.

This is wheretoolset comes in:

• Version Management: Specify exact tool versions to avoid breaking changes during updates.
• Easy Upgrades: When you're ready, upgrade all tools to their latest versions with a single command.
• Reproducibility: Enable consistent behavior across machines, making builds and code checks more reliable.

You can installtoolset using either Go or Homebrew:

go install github.com/kazhuravlev/toolset/cmd/toolset@latest

brew install kazhuravlev/toolset/toolset

toolset allows you to initialize a configuration, add tools, install specific versions, and run or upgrade them. Beloware the basic commands:

Create atoolset.json configuration file in the specified directory:

# Init an empty projecttoolset init.# ...or from existing one.toolset init --copy-from git+https://gist.github.com/3f16049ce3f9f478e6b917237b2c0d88.git:/sample-toolset.json

toolset supports multiple runtimes for installing tools. Usego runtime to build from source, orgh runtime todownload pre-built binaries from GitHub releases (faster for tools like golangci-lint).

Explicitly add tool to your configuration. They have an priority on top of includes.

# Add using Go runtime (builds from source)toolset add go github.com/golangci/golangci-lint/cmd/golangci-lint@v1.60.2# Add the latest version (automatically resolves to the most recent version)toolset add go github.com/golangci/golangci-lint/cmd/golangci-lint@latest# Add using GitHub releases runtime (downloads pre-built binary - faster!)toolset add gh golangci/golangci-lint@v1.61.0

When you bootstrap a new repository and want to have a copy of the.toolset.json file from an existing repository.

# ... from local filetoolset add --copy-from path/to/another/.toolset.json# ... from remote httptoolset add --copy-from https://gist.githubusercontent.com/kazhuravlev/3f16049ce3f9f478e6b917237b2c0d88/raw/44a2ea7d2817e77e2cd90f29343788c864d36567/sample-toolset.json# ... from git repo (by ssh)toolset add --copy-from git+ssh://git@gist.github.com:3f16049ce3f9f478e6b917237b2c0d88.git:/sample-toolset.json# ... from git repo (by https)toolset add --copy-from git+https://gist.github.com/3f16049ce3f9f478e6b917237b2c0d88.git:/sample-toolset.json

The included source will be explicitly registered. This URL will be added to your.toolset.json file.

# ... from local filetoolset add --include /path/to/.toolset.json# ... from remote httptoolset add --include https://gist.githubusercontent.com/kazhuravlev/3f16049ce3f9f478e6b917237b2c0d88/raw/44a2ea7d2817e77e2cd90f29343788c864d36567/sample-toolset.json# ... from git repo (by ssh)toolset add --include git+ssh://git@gist.github.com:3f16049ce3f9f478e6b917237b2c0d88.git# ... from git repo (by https)toolset add --include git+https://gist.github.com/3f16049ce3f9f478e6b917237b2c0d88.git

Add one or more tags to each tool. It will allow you to install only selected tools. Tools that have a tag can befiltered intoolset sync andtoolset upgrade. See the docs bellow.

# Add linter to group `linters` and `ci`toolset add --tags linters,ci go github.com/golangci/golangci-lint/cmd/golangci-lint# Add tools to group `ci`toolset add --tags ci go github.com/jstemmer/go-junit-report/v2@latesttoolset add --tags ci go github.com/boumenot/gocover-cobertura

Important Feature:toolset supports installing tools directly from GitHub releases using thegh runtime. This isparticularly useful for tools likegolangci-lint that provide pre-built binaries, making installation much faster thanbuilding from source.

# Install golangci-lint from GitHub releases (much faster than building from source)toolset add gh golangci/golangci-lint@v1.61.0toolset sync# Run the tooltoolset run golangci-lint version# Upgrade to a newer releasetoolset upgrade golangci-lint

Thegh runtime downloads pre-compiled binaries from GitHub releases, which is significantly faster than thegoruntime that builds from source. This is especially beneficial for large tools like golangci-lint.

Authentication: For private repositories or to avoid rate limits, setGITHUB_TOKEN orTOOLSET_GITHUB_TOKENenvironment variable:

export GITHUB_TOKEN=ghp_your_token_heretoolset add gh owner/private-repo@v1.0.0

In order to install tool with concrete golang version:

# Add a new runtime (it will installed at the moment)toolset runtime add go@1.22.10# Check that it was addedtoolset runtime list

And install tool with specific version:

toolset add go@1.22.10 github.com/golangci/golangci-lint/cmd/golangci-lint@v1.59.0toolset synctoolset list

Ensure all specified tools are installed or updated to the defined versions:

# Make sure that all tools installed with a correct version.toolset sync# ...do it only for some set of toolstoolset sync --tags linters

By default, tools are installed into~/.cache/toolset.

Execute any installed tool with its corresponding arguments. For example, to rungolangci-lint:

toolset run golangci-lint run --fix ./...

To upgrade all tools to their latest available versions, run:

# Upgrade all toolstoolset upgrade# Upgrade only specific toolstoolset upgrade --tags ci

This command ensures all tools in your toolset.json configuration are updated to the latest version.

To get an abs path to installed tool you can just use atoolset which:

# Install some tool. For example - goimportstoolset add go golang.org/x/tools/cmd/goimportstoolset sync# Get an abs path to installed tooltoolset which goimports

This command returns an abs path to goimports like that:

/Users/username/.cache/toolset/go1.23/.goimports___v0.21.0/goimports

You can usetoolset remove in very similar order liketoolset add ortoolset run. This operation will removerequested binaries and some meta info.

# Install some tool. For example - goimportstoolset add go golang.org/x/tools/cmd/goimportstoolset sync# Remove tool by callingtoolset remove goimports

Here’s anexample of a directory with the toolset. To try it out, follow these steps:

Install the toolset and run:

git clone git@github.com:kazhuravlev/toolset.gitcd toolset/example# Install all toolstoolset sync# ... and check installed toolsls~/.cache/toolset# Run installed tooltoolset run gt --repo ../ tag last# List installed toolstoolset list# List installed tools that was never usedtoolset list --unused

toolset supports multiple runtime environments for installing tools:

Builds tools from Go source code. Supports any Go module that can be built withgo install.

toolset add go github.com/golangci/golangci-lint/cmd/golangci-lint@v1.61.0toolset add go golang.org/x/tools/cmd/goimports@latest

Advantages:

• Works with any Go module
• Can use specific Go versions for building
• Full source code compilation

Disadvantages:

• Slower installation (needs to compile from source)

Downloads pre-built binaries directly from GitHub releases.

toolset add gh golangci/golangci-lint@v1.61.0toolset add gh owner/repository@v2.5.0

Advantages:

• Much faster installation (downloads pre-compiled binaries)
• No compilation required
• Perfect for large tools like golangci-lint

Disadvantages:

• Only works with projects that publish release binaries
• Requires consistent release naming conventions

When to use which:

• Usegh for tools that provide pre-built binaries (faster)
• Usego for tools without releases or when you need specific Go versions

Contributions are welcome! Feel free to open issues or submit pull requests to improve toolset.

Which files should be added into git index?

• .toolset.json should be added into git index. This is likego.mod orpackage.json.
• .toolset.lock.json should be added into git index. This is likego.sum or another lock files.

Is that possible to change directory that contains a binary files?

Yes. You can change it in your.toolset.json.

I have a strange behaviour. What I should do to fix that?

Main command -toolset sync. This should fix the all problems. In case when it is not fixed - create an issue.

Where toolset store tools?

All tools and stats file stored into~/.cache/toolset directory. You can delete this directory any time. Toolset willdownload necessary tools at the next run.

How to change directory where tools stored?

Just export variable like thatexport TOOLSET_CACHE_DIR=/tmp/some-directory.

How to change directory where.toolset.json and.toolset.lock.json stored?

Just export variable like thatexport TOOLSET_SPEC_DIR=.some/directory. Toolset will try to find spec files into thisdir.

How do I use GitHub authentication for the gh runtime?

Set theGITHUB_TOKEN orTOOLSET_GITHUB_TOKEN environment variable with your GitHub personal access token. This isuseful for:

• Accessing private repositories
• Avoiding GitHub API rate limits
• CI/CD environments

export GITHUB_TOKEN=ghp_your_token_heretoolset add gh owner/private-repo@v1.0.0

What environment variables does toolset support?

• TOOLSET_CACHE_DIR - Change where tools are stored (default:~/.cache/toolset)
• TOOLSET_SPEC_DIR - Change where.toolset.json and.toolset.lock.json are located
• GITHUB_TOKEN orTOOLSET_GITHUB_TOKEN - GitHub authentication for thegh runtime