---

terrajux

terrajux diffs the source code of a terraform root module project, along with the source of all its transitive module dependencies, between two git refs.

how?

• ensure that terraform and git are installed and available in your system's PATH.
• download the latest release archive named for the os and arch appropriate for your system.
• decompress and extract the archive.
  • tar -zxvf terrajux_<version>_<os>_<arch>.tar.gz will do on many systems.
• terrajux is distributed as a self-contained binary. simply move the terrajux binary to a location of your choosing. for many, this will be somewhere in your system's PATH such as /usr/local/bin/ or ~/bin/.
• on macos it may be necessary to explictly inform the system that terrajux is an approved program.
  • navigate to the directory containing terrajux via terminal or finder.
  • run open . if using the terminal.
  • right-click on terrajux and select open.

try it!

terrajux giturl v1ref v2ref [subpath]

# example:
terrajux https://github.com/terraform-aws-modules/terraform-aws-iam.git v3.15.0 master modules/iam-user

why?

terraform provides primitives for building and maintaining complex, distributed infrastructure projects through composition of reusable modules. module dependencies can be stored in source control systems, versioned, pinned, and automatically fetched at runtime by terraform init. these tools provide infrastructure engineers the means to consistently reproduce infrastructure delivery tooling with the exact version of all module and provider dependencies used previously. they may then choose to try a new version of some module in the development environment, and only promote those changes to staging or production when it is safe to do so.

such a system has many benefits but also some tradeoffs. a complex infrastructure project may have tens of modules, and each of those modules may have their own module dependencies, and so forth.

during the course of troubleshooting, outage investigation, or postmortems it can be helpful see exactly what code changed across two versions of a project's root module and all of its dependencies without bouncing between artifacts and source code distributed among many git repositories.

terrajux aims to provide a user-friendly tool for viewing such changes.

terrajux does not embed terraform. i recommend using the excellent tfenv version manager to manage multiple terraform versions and maintaining appropriate .terraform-version files in your root projects and submodules to limit side effects of version incompatibilities. have you ever inadvertently upgraded a project's shared terraform remote state by using the wrong version of terraform locally? i have. don't do that.

who?

terrajux is primarily aimed at site reliability and infrastructure engineers managing systems built from nested terraform modules spread across many repositories.

it is maintained primarily by rich henning, a software engineer living and working in philadelphia.

@mdb also contributes to this project and created terrajux-action, which facilitates the use of terrajux in a GitHub Actions workflow.

why "terrajux"?

why not terradiff?

terradiff is an existing project used to detect drift of terraform-managed infrastructure.

why not ________?

tdiff is concise but used as the name of some command line utilities and tree difference libraries.

also, many of the tools intended for use within the terraform ecosystem have names beginning with terra, so i wanted to stick with that convention.

terrac[o]mp translates from speech to text with some ambiguity.

juxtapose popped into my head while considering the possibilities, and so we have terrajux.

faq

what is happening behind the scenes?

in short, terrajux:

• performs shallow clones of the the specified git repository at the supplied refs
• initializes terraform with -backend=false to download all module dependencies without touching the terraform state backend
• displays a recursive diff of the initialized projects

what platforms are supported?

• macos and linux builds are fully tested for every pr and release
• *bsd and solaris builds are untested but should work
• windows builds are disabled pending some portability issues

how can i use ________ to view the diff?

try the -difftool option.

-difftool accepts a go template that can be used to format commands for an alternative diff viewer. the strings {{.V1}} and {{.V2}} will be replaced by the v1ref and v2ref args supplied to terrajux at runtime.

to use the compare folders plugin in vs code, for example, try:

-difftool 'COMPARE_FOLDERS=DIFF code {{.V1}} {{.V2}}'

to avoid typing this every time, consider creating an alias in your shell's profile, such as:

alias terrajux="terrajux -difftool 'opendiff {{.V1}} {{.V2}}'"

is it possible to use this in GitHub's pull request workflow?

sure! please check out @mdb's terrajux-action for GitHub Actions.

i'm seeing a stale diff for a branch ref or getting strange errors during initialization. what gives?

try clearing the cache with the -clearcache option.

terrajux keeps a local cache of checkouts and initialized terraform modules to speed up subsequent diffs of long-lived release tags. the cache key is a concatentation of git url (sans scheme) and ref. when diffing dynamic refs such as branches (or a tag that has been deleted and repointed), the cache entry may be stale. you'll know this is the case if output displays something like Found <repo>@<ref> in cache. Skipping clone.

how do i report a bug?

woops, sorry about that! please submit a bug report.

how do i request a feature?

please submit a feature request to start the conversation. once that's done, we can work on it or consider pull requests.

how can i contribute (documentation, code, resources, etc.)?

awesome! your kindness is very much appreciated. please check out the contribution guidelines for more information.

license

this project is released under the apache 2.0 license.