{"id":13607324,"url":"https://github.com/rhenning/terrajux","last_synced_at":"2025-04-11T21:51:02.322Z","repository":{"id":49563565,"uuid":"371222064","full_name":"rhenning/terrajux","owner":"rhenning","description":"terrajux diffs the source code of a terraform project and all of its transitive module dependencies between two git refs.","archived":false,"fork":false,"pushed_at":"2021-06-14T13:26:06.000Z","size":107,"stargazers_count":11,"open_issues_count":12,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T17:49:29.518Z","etag":null,"topics":["cli","cloud","cloud-management","devops","devops-tools","golang","infrastructure-as-code","terraform"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhenning.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-27T02:21:12.000Z","updated_at":"2024-11-24T04:43:24.000Z","dependencies_parsed_at":"2022-09-02T12:31:11.027Z","dependency_job_id":null,"html_url":"https://github.com/rhenning/terrajux","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhenning%2Fterrajux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhenning%2Fterrajux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhenning%2Fterrajux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhenning%2Fterrajux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhenning","download_url":"https://codeload.github.com/rhenning/terrajux/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248487733,"owners_count":21112188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cloud","cloud-management","devops","devops-tools","golang","infrastructure-as-code","terraform"],"created_at":"2024-08-01T19:01:17.672Z","updated_at":"2025-04-11T21:51:02.296Z","avatar_url":"https://github.com/rhenning.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"[![current-release](https://img.shields.io/github/release/rhenning/terrajux.svg?style=for-the-badge)](https://github.com/rhenning/terrajux/releases/latest)\n[![build-status](https://img.shields.io/github/workflow/status/rhenning/terrajux/test/main?style=for-the-badge)](https://github.com/rhenning/terrajux/actions/workflows/test.yml?query=workflow%3Atest+branch%3Amain)\n[![report-card](https://goreportcard.com/badge/github.com/rhenning/terrajux?style=for-the-badge)](https://goreportcard.com/report/github.com/rhenning/terrajux)\n[![license-info](https://img.shields.io/github/license/rhenning/terrajux?style=for-the-badge\u0026color=orange)](https://www.apache.org/licenses/LICENSE-2.0)\n\n[![pb-goreleaser](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-goreleaser-hotpink.svg?style=for-the-badge)](https://github.com/goreleaser)\n[![pb-semanticrelease](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-hotpink.svg?style=for-the-badge)](https://github.com/semantic-release/semantic-release)\n[![pb-golangcilint](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-golangci--lint-hotpink.svg?style=for-the-badge)](https://golangci-lint.run/)\n[![pb-gosec](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-gosec-hotpink.svg?style=for-the-badge)](https://securego.io/)\n\n\n\u003c!--\n[![Codecov branch](https://img.shields.io/codecov/c/github/rhenning/terrajux/main.svg?style=for-the-badge)](https://codecov.io/gh/rhenning/terrajux)\n[![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=for-the-badge)](http://godoc.org/github.com/rhenning/terrajux)\n--\u003e\n\n---\n\n# terrajux\n\n`terrajux` [diff](https://en.wikipedia.org/wiki/Diff)s the source code of a\n[terraform](https://github.com/hashicorp/terraform)\n[root module](https://www.terraform.io/docs/language/modules/index.html#the-root-module) project,\nalong with the source of all its transitive module dependencies, between two git refs.\n\n\n## how?\n\n- ensure that `terraform` and `git` are installed and available in your system's `PATH`.\n- download the [latest release archive](https://github.com/rhenning/terrajux/releases/)\n  named for the os and arch appropriate for your system.\n- decompress and extract the archive.\n  - `tar -zxvf terrajux_\u003cversion\u003e_\u003cos\u003e_\u003carch\u003e.tar.gz` will do on many systems.\n- `terrajux` is distributed as a self-contained binary. simply move the `terrajux`\n  binary to a location of your choosing. for many, this will be somewhere in your\n  system's `PATH` such as `/usr/local/bin/` or `~/bin/`.\n- on macos it may be necessary to explictly inform the system that `terrajux` is\n  an approved program.\n  - navigate to the directory containing `terrajux` via terminal or finder.\n  - run `open .` if using the terminal.\n  - right-click on `terrajux` and select **open**.\n\n**try it!**\n\n```\nterrajux giturl v1ref v2ref [subpath]\n\n# example:\nterrajux https://github.com/terraform-aws-modules/terraform-aws-iam.git v3.15.0 master modules/iam-user\n```\n\n\n## why?\n\nterraform provides primitives for building and maintaining complex, distributed\ninfrastructure projects through [composition of reusable modules](https://www.terraform.io/docs/language/modules/develop/composition.html). module dependencies can be [stored in source control systems](https://www.terraform.io/docs/language/modules/sources.html),\n[versioned, pinned](https://www.terraform.io/docs/language/modules/sources.html#selecting-a-revision),\nand [automatically fetched at runtime by `terraform init`](https://www.terraform.io/docs/cli/commands/init.html#child-module-installation). these tools provide infrastructure engineers the means to\nconsistently reproduce infrastructure delivery tooling with the exact version of all module and\nprovider dependencies used previously. they may then choose to try a new version of some module in\nthe development environment, and only promote those changes to staging or production when it is safe\nto do so.\n\nsuch a system has many benefits but also some tradeoffs. a complex infrastructure project may have\ntens of modules, and each of those modules may have their own module dependencies, and so forth.\n\nduring the course of troubleshooting, outage investigation, or postmortems it can be helpful see\nexactly what code changed across two versions of a project's root module and all of its dependencies\nwithout bouncing between artifacts and source code distributed among many git repositories.\n\n**`terrajux` aims to provide a user-friendly tool for viewing such changes.**\n\n`terrajux` does not embed terraform. i recommend using the excellent\n[`tfenv` version manager](https://github.com/tfutils/tfenv) to manage multiple\nterraform versions and maintaining appropriate `.terraform-version` files in your\nroot projects and submodules to limit side effects of version incompatibilities.\nhave you ever inadvertently upgraded a project's shared terraform remote state by\nusing the wrong version of terraform locally? i have. don't do that.\n\n\n## who?\n\n`terrajux` is primarily aimed at site reliability and infrastructure engineers managing systems\nbuilt from nested terraform modules spread across many repositories.\n\nit is maintained primarily by [rich henning](https://github.com/rhenning), a software engineer living and\nworking in philadelphia.\n\n[@mdb](https://github.com/mdb) also contributes to this project and created [terrajux-action](https://github.com/mdb/terrajux-action), which facilitates the use of `terrajux` in a [GitHub Actions](https://github.com/features/actions) workflow.\n\n\n## why \"terrajux\"?\n\n**why not `terradiff`?**\n\n[`terradiff`](https://github.com/jml/terradiff) is an existing project used to detect drift of\nterraform-managed infrastructure.\n\n**why not `________`?**\n\n`tdiff` is concise but used as the name of some command line utilities and tree difference\nlibraries.\n\nalso, many of the tools intended for use within the terraform ecosystem have names beginning with\n`terra`, so i wanted to stick with that convention.\n\n`terrac[o]mp` translates from speech to text with some ambiguity.\n\n_juxtapose_ popped into my head while considering the possibilities, and so we have `terrajux`.\n\n\n## faq\n\n\u003e what is happening behind the scenes?\n\nin short, `terrajux`:\n- performs shallow clones of the the specified git repository at\n  the supplied refs\n- initializes terraform with `-backend=false` to download all module\n  dependencies without touching the terraform state backend\n- displays a recursive diff of the initialized projects\n\n\n\u003e what platforms are supported?\n\n- macos and linux builds are fully tested for every pr and release\n- *bsd and solaris builds are untested but _should_ work\n- windows builds are disabled pending [some portability issues](https://github.com/rhenning/terrajux/issues)\n\n\n\u003e how can i use ________ to view the diff?\n\ntry the `-difftool` option.\n\n`-difftool` accepts a [go template](https://golang.org/pkg/text/template/) that\ncan be used to format commands for an alternative diff viewer. the strings\n`{{.V1}}` and `{{.V2}}` will be replaced by the `v1ref` and `v2ref` args\nsupplied to `terrajux` at runtime.\n\nto use the [compare folders plugin](https://marketplace.visualstudio.com/items?itemName=moshfeu.compare-folders)\nin [vs code](https://code.visualstudio.com/), for example, try:\n\n```\n-difftool 'COMPARE_FOLDERS=DIFF code {{.V1}} {{.V2}}'\n```\n\nto avoid typing this every time, consider creating an alias in\n[your shell's profile](https://en.wikipedia.org/wiki/Unix_shell#Configuration_files),\nsuch as:\n\n```\nalias terrajux=\"terrajux -difftool 'opendiff {{.V1}} {{.V2}}'\"\n```\n\n\u003e is it possible to use this in GitHub's pull request workflow?\n\nsure! please check out [@mdb](https://github.com/mdb)'s [terrajux-action](github.com/mdb/terrajux-action) for [GitHub Actions](https://github.com/features/actions).\n\n\u003e i'm seeing a stale diff for a branch ref or getting strange errors during\n  initialization. what gives?\n\ntry clearing the cache with the `-clearcache` option.\n\n`terrajux` keeps a local cache of checkouts and initialized terraform modules\nto speed up subsequent diffs of long-lived release tags. the cache key is a\nconcatentation of git url (sans scheme) and ref. when diffing dynamic refs\nsuch as branches (or a tag that has been deleted and repointed), the cache entry\nmay be stale. you'll know this is the case if output displays something like\n`Found \u003crepo\u003e@\u003cref\u003e in cache. Skipping clone.`\n\n\n\u003e how do i report a bug?\n\nwoops, sorry about that! please [submit a bug report](https://github.com/rhenning/terrajux/issues/new/choose).\n\n\n\u003e how do i request a feature?\n\nplease [submit a feature request](https://github.com/rhenning/terrajux/issues/new/choose) to start the conversation. once that's done, we can work on it or\nconsider [pull requests](https://github.com/rhenning/terrajux/pulls).\n\n\n\u003e how can i contribute (documentation, code, resources, etc.)?\n\nawesome! your kindness is very much appreciated. please\n[check out the contribution guidelines](https://github.com/rhenning/terrajux/contribute)\nfor more information.\n\n\n## license\n\nthis project is released under the [apache 2.0 license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhenning%2Fterrajux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhenning%2Fterrajux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhenning%2Fterrajux/lists"}