Version Selection

This respository is home two to major versions of HCL: the original implementation HCL 1, and the later reworking of it HCL 2.

In order to minimize problems for dependent codebases that were not yet using Go Modules, we initially left the default branch referring to HCL 1 and kept HCL 2 development in the hcl2 branch. However, with HCL 2 now being over a year old and with Go Modules being more widely deployed we have now switched so that the main branch is HCL 2, where most new development will occur, and HCL 1 maintenance will now take place in the hcl1 branch.

If you are using Go Modules then you don't generally need to worry about the branch names, because go.mod dependencies refer to specific tags or commits rather than to branches.

We recommend that all new projects that are considering using HCL should use HCL 2. It has a more robust parser capable of producing better error messages, a better architecture for parsing JSON as HCL, and incorporates an expression language that was previously separated in the related codebase HIL.

To use HCL 2 in your project, use Go Modules in your project select the latest HCL 2 release as follows:

go get github.com/hashicorp/hcl/v2

The /v2 suffix on the module path above will cause the Go toolchain to select the latest release from major version 2.

To install HCL 1 using Go Modules, use a module path with no version suffix:

go get github.com/hashicorp/hcl

This will select the latest release of major version 1. If you are using Go Modules mode, you can safely depend on both major versions of HCL at the same time in your project, in case you wish to migrate from HCL 1 to HCL 2.

If your project is not using Go Modules mode, the Go toolchain will only be able to select the latest commit from the main branch, and therefore this codebase is no longer compatible with the legacy GOPATH mode. If you need to use HCL with a repository that cannot yet use Go Modules, you'll need to use a legacy Go dependency vendoring tool, such as govendor or dep, to copy the source code from one of the v1.x.y tags into your own repository, using the legacy Go 1.11 vendoring mechanism.

Refer to the index of all HCL versions on the Go packages site for details on exact versions you can select.

Contributing

If you wish to contribute to HCL 2, you should not need to do anything special when opening your pull request because the default branch, main, is the target for new HCL 2 development.

HCL 1 is now in maintenence mode and we are unlikely to accept any new feature requests or implementations into that version. For compatibility reasons, we also don't intend to address any parser or decoder bugs that would change behavior for existing applications depending on HCL 1. Our sole focus for ongoing HCL 1 development will be severe bugs such as crashes. However, if you still want to contribute to HCL 1 with those caveats in mind, be sure to configure your pull request to target the hcl1 branch.