Skip to content
On this page

Create a new Terramate project

If you already have a project versioned on Git setting up Terramate is as easy as just installing Terramate. Terramate comes with sensible defaults so just using it inside a pre existent Git repository should not require any configurations.

The exception being repositories that have a default remote branch other than origin/main, in that case to make change detection work you will need to set a customized project configuration.

If you want to play around with Terramate from scratch locally you can also setup a local git repository:

playground=$(mktemp -d)
local_origin=$(mktemp -d)

git init -b main "${playground}"
git init -b main "${local_origin}"  --bare

cd "${playground}"
git remote add origin "${local_origin}"

echo "My Terramate Playground" >

git add
git commit -m "first commit"
git push --set-upstream origin main

# Start using terramate

Terramate can also work without any VCS setup, it will only require a Terramate configuration at the top level directory of the project

playground=$(mktemp -d)
cd "${playground}"

cat > <<- EOM
terramate {
  config {

# Start using terramate

In a setup with no VCS, change detection features will not be available.

You can also check our live example.

Initializing existing infrastructure

If you already have a IaC repository containing multiple Terraform stacks then you can use the command below to easily detect and create Terramate stacks automatically:

terramate create --all-terraform

The command above will scan the repository looking for Terraform directories containing a backend or provider configuration, which commonly indicates that it's a Terraform stack.