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.
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.