From 3baeb821f618e378dc5d85acdf6017593308074a Mon Sep 17 00:00:00 2001 From: Dino Korah <691011+codemedic@users.noreply.github.com> Date: Mon, 10 Nov 2025 10:58:59 +0000 Subject: [PATCH 1/4] Replace Python script with Bash script for version retrieval --- LICENSE | 21 ++++++ README.md | 175 ++++++++++++++++++++++++++++++++++++++++++++---- git_describe.sh | 26 +++++++ main.tf | 2 +- 4 files changed, 210 insertions(+), 14 deletions(-) create mode 100644 LICENSE create mode 100755 git_describe.sh diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..36df5e7 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2018 Red Matter and contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index fad0d21..ffaff15 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,172 @@ # git-version -Module for retrieving versions from the git repo from which the parent module is running. +Terraform module for retrieving version information from the Git repository in which the parent module is running. This module uses `git describe` to generate semantic version strings based on Git tags, commit history, and working tree state. -## Overrides +## Features -The version returned can be overridden via the environment and via a passed in override variable. +- **Zero external dependencies** - Only requires Bash (3.2+) and Git +- **Cross-platform compatible** - Works on Linux, macOS, and other Unix-like systems +- **Flexible version override system** - Support for environment variables and explicit overrides +- **CI/CD friendly** - Handles scenarios where Git may not be available during apply-time -### Environment +## Dependencies -By default, if the `TF_MODULE_VERSION` environment variable is set, this module will return the value of that variable -instead of using Git to determine a version. +This module requires the following to be available in the execution environment: -The environment variable to check can be changed by setting the `version_environment_variable` variable. +| Dependency | Minimum Version | Purpose | Notes | +|------------|-----------------|---------|-------| +| **Terraform** | >= 0.12.0 | Infrastructure as Code runtime | Required | +| **Bash** | >= 3.2 | Shell script execution | Compatible with macOS default bash | +| **Git** | Any | Version control system | Must be available in PATH unless using overrides | -### Override variable +### Platform Compatibility -The `version_override` variable defaults to `null`, but if set will be returned. -In this case neither the Git repo nor the environment will be checked. +- ✅ **Linux** - All distributions with bash and git +- ✅ **macOS** - Compatible with default bash 3.2 (no Homebrew updates required) +- ✅ **Windows** - Git Bash, WSL, or Cygwin environments +- ✅ **CI/CD** - Works with environment variable overrides when Git is unavailable -This can be useful as a way to allow parent modules to override the version via a variable without needing to implement -logic of their own to optionally use the module depending on the status of their override variable. -Instead, they can just pass the override variable in and if it's `null` then it will be ignored. +## Usage + +### Basic Usage + +```hcl +module "version" { + source = "path/to/git-version" +} + +output "current_version" { + value = module.version.version +} +``` + +### With Custom Environment Variable + +```hcl +module "version" { + source = "path/to/git-version" + + version_environment_variable = "MY_CUSTOM_VERSION_VAR" +} +``` + +### With Explicit Override + +```hcl +module "version" { + source = "path/to/git-version" + + version_override = "1.2.3-custom" +} +``` + +## Version Resolution + +The module resolves versions using the following priority order (highest to lowest): + +### 1. Explicit Override (Highest Priority) + +The `version_override` variable directly sets the version, bypassing both environment variables and Git. + +```hcl +version_override = "2.0.0-rc1" +``` + +**Use case:** Parent modules that need to conditionally override versions without implementing their own logic. + +### 2. Environment Variable Override + +By default, the `TF_MODULE_VERSION` environment variable is checked. If set, its value is returned instead of querying Git. + +```bash +export TF_MODULE_VERSION=1.5.0 +terraform plan +``` + +The environment variable name can be customized: + +```hcl +version_environment_variable = "DEPLOYMENT_VERSION" +``` + +**Use case:** CI/CD pipelines where Git may not be available during `terraform apply`, or when you want to pin a specific version for a deployment. + +### 3. Git Describe (Default Fallback) + +If no overrides are set, the module executes: + +```bash +git describe --tags --long --dirty --always +``` + +This produces version strings like: + +- `1.2.3-0-ga1b2c3d` - On a tagged commit +- `1.2.3-5-ga1b2c3d` - 5 commits after tag 1.2.3 +- `1.2.3-5-ga1b2c3d-dirty` - Same as above with uncommitted changes +- `a1b2c3d` - No tags found (falls back to commit hash) + +**Use case:** Standard development workflow where Git history accurately reflects versioning. + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|----------| +| `version_environment_variable` | Name of the environment variable to check for version override | `string` | `"TF_MODULE_VERSION"` | No | +| `version_override` | Explicit version string to return (bypasses Git and environment) | `string` | `null` | No | + +## Outputs + +| Name | Description | +|------|-------------| +| `version` | The resolved version string from Git, environment, or override | + +## How It Works + +The module uses Terraform's `external` data source to execute a bash script ([git_describe.sh](git_describe.sh)) that: + +1. Checks if the specified environment variable contains a version +2. If not, executes `git describe --tags --long --dirty --always` +3. Returns the version as JSON: `{"version": "..."}` +4. Falls back to `"UNKNOWN"` if Git command fails + +## CI/CD Integration + +### GitHub Actions Example + +```yaml +- name: Terraform Plan + env: + TF_MODULE_VERSION: ${{ github.ref_name }} + run: terraform plan +``` + +### GitLab CI Example + +```yaml +terraform: + variables: + TF_MODULE_VERSION: $CI_COMMIT_TAG + script: + - terraform apply +``` + +### Jenkins Example + +```groovy +environment { + TF_MODULE_VERSION = "${env.GIT_TAG}" +} +``` + +## Migration Notes + +**Version 1.2.0+**: Removed Python dependency in favor of Bash. The Python script (`git_describe.py`) is no longer used or required. If you have older versions of this module pinned, no changes are needed - the bash implementation produces identical output. + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## Contributing + +When modifying the bash script, ensure compatibility with bash 3.2+ for macOS support. Test on both modern Linux (bash 5.x) and macOS (bash 3.2) before submitting changes. diff --git a/git_describe.sh b/git_describe.sh new file mode 100755 index 0000000..0a10fc7 --- /dev/null +++ b/git_describe.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +# Compatible with bash 3.2+ (including macOS default bash) + +version="" + +# Check if an environment variable name was passed as argument +if [ $# -ge 1 ]; then + # Indirect variable expansion - get the value of the variable named in $1 + # This syntax works in bash 3.2+ + eval "version=\${$1}" +fi + +# If version is still empty, try to get it from git +if [ -z "$version" ]; then + # Redirect stderr to /dev/null to suppress error messages + if version=$(git describe --tags --long --dirty --always 2>/dev/null); then + # Success - version is already set + : + else + # Git command failed + version="UNKNOWN" + fi +fi + +# Output JSON - using printf for better portability and to avoid echo quirks +printf '{"version": "%s"}\n' "$version" diff --git a/main.tf b/main.tf index 0f8ada2..8173dd4 100644 --- a/main.tf +++ b/main.tf @@ -1,4 +1,4 @@ data "external" "version" { count = var.version_override == null ? 1 : 0 - program = ["python", "${path.module}/git_describe.py", var.version_environment_variable] + program = ["bash", "${path.module}/git_describe.sh", var.version_environment_variable] } From 6ed643f91223ba205ecd5ab56cf4759a596353df Mon Sep 17 00:00:00 2001 From: Dino Korah <691011+codemedic@users.noreply.github.com> Date: Mon, 10 Nov 2025 11:07:55 +0000 Subject: [PATCH 2/4] Escape special characters in JSON output for better validity --- git_describe.sh | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/git_describe.sh b/git_describe.sh index 0a10fc7..e28c3b5 100755 --- a/git_describe.sh +++ b/git_describe.sh @@ -22,5 +22,10 @@ if [ -z "$version" ]; then fi fi -# Output JSON - using printf for better portability and to avoid echo quirks -printf '{"version": "%s"}\n' "$version" +# Output JSON - escape special characters to ensure valid JSON +# Using bash 3.2+ compatible parameter expansion: ${var//pattern/replacement} +# Order matters: escape backslashes first (to avoid double-escaping), then quotes +version_escaped="${version//\\/\\\\}" # Replace \ with \\ +version_escaped="${version_escaped//\"/\\\"}" # Replace " with \" + +printf '{"version": "%s"}\n' "$version_escaped" From b0e776268a46ee7db9c1168922dc75cf3c0a7a00 Mon Sep 17 00:00:00 2001 From: Dino Korah <691011+codemedic@users.noreply.github.com> Date: Mon, 10 Nov 2025 11:48:13 +0000 Subject: [PATCH 3/4] Add Windows compatibility guide to README and create dedicated WINDOWS.md file --- README.md | 8 +- WINDOWS.md | 361 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 368 insertions(+), 1 deletion(-) create mode 100644 WINDOWS.md diff --git a/README.md b/README.md index ffaff15..a53825f 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ Terraform module for retrieving version information from the Git repository in which the parent module is running. This module uses `git describe` to generate semantic version strings based on Git tags, commit history, and working tree state. +> **Windows Users:** See the [Windows Compatibility Guide](WINDOWS.md) for detailed setup instructions and troubleshooting. + ## Features - **Zero external dependencies** - Only requires Bash (3.2+) and Git @@ -23,9 +25,11 @@ This module requires the following to be available in the execution environment: - ✅ **Linux** - All distributions with bash and git - ✅ **macOS** - Compatible with default bash 3.2 (no Homebrew updates required) -- ✅ **Windows** - Git Bash, WSL, or Cygwin environments +- ✅ **Windows** - Git Bash, WSL, or Cygwin environments ([detailed Windows guide](WINDOWS.md)) - ✅ **CI/CD** - Works with environment variable overrides when Git is unavailable +**Windows Users:** Git Bash is automatically included with Git for Windows. No additional installation required. See the [Windows Compatibility Guide](WINDOWS.md) for details. + ## Usage ### Basic Usage @@ -163,6 +167,8 @@ environment { **Version 1.2.0+**: Removed Python dependency in favor of Bash. The Python script (`git_describe.py`) is no longer used or required. If you have older versions of this module pinned, no changes are needed - the bash implementation produces identical output. +**For Windows users:** Git Bash (included with Git for Windows) provides all required functionality. No additional setup needed beyond Git, which is already required for version control. See [WINDOWS.md](WINDOWS.md) for comprehensive Windows compatibility information, troubleshooting, and FAQs. + ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. diff --git a/WINDOWS.md b/WINDOWS.md new file mode 100644 index 0000000..dfc93fb --- /dev/null +++ b/WINDOWS.md @@ -0,0 +1,361 @@ +# Windows Compatibility Guide + +This document provides comprehensive guidance for using the `terraform-git-version` module on Windows systems. + +## Table of Contents + +- [Quick Start](#quick-start) +- [Prerequisites](#prerequisites) +- [Installation Options](#installation-options) +- [How It Works](#how-it-works) +- [Troubleshooting](#troubleshooting) +- [Frequently Asked Questions](#frequently-asked-questions) +- [Alternative: Using Python](#alternative-using-python) + +## Quick Start + +**TL;DR:** If you have Git installed on Windows (which you need for Terraform development anyway), this module will work without any additional setup. + +```bash +# In Git Bash (comes with Git for Windows) +cd your-terraform-project +terraform init +terraform plan +``` + +## Prerequisites + +### Required + +| Software | Why It's Required | Typically Installed | +|----------|-------------------|---------------------| +| **Git for Windows** | Provides both the `git` command AND Git Bash shell | ✅ Yes - required for version control | +| **Terraform CLI** | Infrastructure as Code runtime | ✅ Yes - required for Terraform development | + +### Not Required + +| Software | Status | +|----------|--------| +| **Python** | ❌ Not needed (removed in v1.2.0+) | +| **WSL/WSL2** | ❌ Not needed (but works if you have it) | +| **Cygwin** | ❌ Not needed (but works if you have it) | +| **MinGW** | ❌ Not needed (but works if you have it) | + +## Installation Options + +### Option 1: Git Bash (Recommended) + +Git Bash is automatically installed with Git for Windows and is the standard environment for Terraform development on Windows. + +#### Step 1: Install Git for Windows (if not already installed) + +1. Download Git for Windows from [https://git-scm.com/download/win](https://git-scm.com/download/win) +2. Run the installer with default settings +3. Git Bash will be installed automatically + +#### Step 2: Verify Installation + +Open **Git Bash** (not CMD or PowerShell) and run: + +```bash +# Check Git is available +git --version +# Expected output: git version 2.x.x.windows.x + +# Check Bash is available +bash --version +# Expected output: GNU bash, version 4.x.x or higher + +# Check Terraform is available +terraform version +# Expected output: Terraform v1.x.x or higher +``` + +#### Step 3: Use the Module + +```hcl +# main.tf +module "version" { + source = "github.com/your-org/terraform-git-version" +} + +output "version" { + value = module.version.version +} +``` + +Run in Git Bash: + +```bash +terraform init +terraform plan +``` + +**Result:** The module will execute `bash git_describe.sh` which works natively in Git Bash. + +### Option 2: WSL (Windows Subsystem for Linux) + +If you're using WSL for Terraform development, this module works without any changes. + +```bash +# In WSL terminal +cd /mnt/c/your-terraform-project +terraform plan +``` + +**Note:** Make sure your Terraform project is accessible from WSL. Typically, Windows drives are mounted at `/mnt/c/`, `/mnt/d/`, etc. + +### Option 3: PowerShell with Git Bash + +You can use PowerShell as your main terminal and still run Terraform with this module: + +```powershell +# PowerShell will invoke Git Bash for the script execution +terraform plan +``` + +**How it works:** When Terraform executes `program = ["bash", "..."]`, Windows will find `bash.exe` from Git for Windows (added to PATH during installation). + +## How It Works + +### Execution Flow on Windows + +1. **Terraform invokes the external data source:** + ```hcl + data "external" "version" { + program = ["bash", "${path.module}/git_describe.sh", var.version_environment_variable] + } + ``` + +2. **Windows finds bash.exe:** + - Git for Windows adds `C:\Program Files\Git\bin\` to your PATH + - This includes `bash.exe`, `git.exe`, and other Unix tools + +3. **Bash script executes:** + - Reads environment variable (if specified) + - Runs `git describe --tags --long --dirty --always` + - Returns JSON: `{"version": "..."}` + +4. **Terraform parses the JSON output** + +### Why This Works Seamlessly + +- ✅ **Git Bash is included** with Git for Windows (no extra install) +- ✅ **PATH is configured** automatically during Git installation +- ✅ **No credential issues** - uses the same Git credentials as your normal workflow +- ✅ **No WSL overhead** - runs natively on Windows via Git Bash + +## Troubleshooting + +### Error: "bash: command not found" or "program cannot be found" + +**Cause:** Git for Windows is not installed or `bash.exe` is not in your PATH. + +**Solution:** + +1. Install Git for Windows: [https://git-scm.com/download/win](https://git-scm.com/download/win) +2. Verify PATH includes Git: + ```powershell + # In PowerShell + $env:PATH -split ';' | Select-String 'Git' + # Should show: C:\Program Files\Git\bin or similar + ``` +3. If not in PATH, add it: + - Open "Environment Variables" in Windows + - Add `C:\Program Files\Git\bin` to System PATH + - Restart your terminal + +### Error: "git: command not found" + +**Cause:** Git is not installed or not in PATH. + +**Solution:** Same as above - Git for Windows provides both `bash.exe` and `git.exe`. + +### Error: Permission denied + +**Cause:** The `git_describe.sh` script doesn't have execute permissions. + +**Solution:** + +```bash +# In Git Bash +chmod +x git_describe.sh +git add git_describe.sh +git commit -m "Fix permissions" +``` + +Or manually on Windows: +```powershell +# In PowerShell (if needed) +icacls git_describe.sh /grant Everyone:RX +``` + +### Module returns "UNKNOWN" + +**Cause:** Git cannot find repository information or there are no tags. + +**Solutions:** + +1. **Check if you're in a Git repository:** + ```bash + git status + # Should NOT show: "fatal: not a git repository" + ``` + +2. **Check for Git tags:** + ```bash + git tag + # If empty, create a tag: + git tag -a v1.0.0 -m "Initial version" + ``` + +3. **Use environment variable override:** + ```hcl + # In your terraform + module "version" { + source = "..." + version_override = "1.0.0" # Bypass Git entirely + } + ``` + +### Terminal: CMD vs PowerShell vs Git Bash + +**Recommendation:** Use **Git Bash** for Terraform commands on Windows. + +| Terminal | Works? | Notes | +|----------|--------|-------| +| **Git Bash** | ✅ Yes | Recommended - native bash environment | +| **PowerShell** | ✅ Yes | Works if Git Bash is in PATH | +| **CMD** | ✅ Yes | Works if Git Bash is in PATH | +| **WSL** | ✅ Yes | Full Linux environment | + +## Frequently Asked Questions + +### Q: Do I need to install WSL? + +**A:** No. Git Bash (included with Git for Windows) is sufficient. WSL works but is not required. + +### Q: Do I need Python? + +**A:** No. As of version 1.2.0+, the Python dependency has been removed. The module now uses Bash exclusively. + +### Q: What about AWS credentials or cloud provider setup? + +**A:** This module doesn't interact with cloud providers at all. It only: +- Reads an optional environment variable +- Executes `git describe` to get version information +- Returns the result as JSON + +Your AWS/Azure/GCP credentials are handled by Terraform itself, not by this module. + +### Q: Will this work in CI/CD on Windows? + +**A:** Yes! Most Windows CI/CD environments (GitHub Actions, GitLab CI, Azure DevOps, Jenkins) include Git and Git Bash by default. + +**Example - GitHub Actions:** +```yaml +- name: Setup Terraform + uses: hashicorp/setup-terraform@v2 + +- name: Terraform Plan + run: terraform plan + # Works automatically - GitHub Actions Windows runners include Git Bash +``` + +### Q: What if I'm behind a corporate proxy? + +**A:** Git proxy configuration works the same way: + +```bash +# Configure Git proxy (affects both Git and Git Bash) +git config --global http.proxy http://proxy.example.com:8080 +git config --global https.proxy http://proxy.example.com:8080 +``` + +This module only uses local Git commands - no network access required (unless fetching remote tags). + +### Q: Can I use this with Terraform Cloud/Enterprise on Windows? + +**A:** Yes. During the `terraform plan` phase (typically run locally), the module will execute on your local Windows machine using Git Bash. The results are then sent to Terraform Cloud as part of the plan. + +If you're running Terraform Cloud agents on Windows, ensure Git is installed on the agent machine. + +## Alternative: Using Python + +If you prefer to use Python instead of Bash (for example, if you already have Python standardized in your environment), the legacy Python script is still available: + +### Option: Keep Python Script + +1. **Revert main.tf to use Python:** + ```hcl + data "external" "version" { + count = var.version_override == null ? 1 : 0 + program = ["python", "${path.module}/git_describe.py", var.version_environment_variable] + } + ``` + +2. **Ensure Python is installed and in PATH:** + ```powershell + # Check Python availability + python --version + # or + python3 --version + ``` + +3. **Install Python if needed:** + - Download from [https://www.python.org/downloads/](https://www.python.org/downloads/) + - During installation, check "Add Python to PATH" + +### Comparison: Bash vs Python + +| Aspect | Bash (Default) | Python (Alternative) | +|--------|----------------|---------------------| +| **Installation** | Included with Git | Separate installation required | +| **Configuration** | Automatic (via Git setup) | Must add to PATH manually | +| **Dependencies** | Git only | Git + Python | +| **Windows Support** | Via Git Bash (included) | Via Python installer | +| **Compatibility** | bash 3.2+ (2007+) | Python 2.7+ or 3.x | +| **Maintenance** | Active | Legacy (deprecated) | + +**Recommendation:** Unless you have a specific requirement for Python, use the default Bash implementation. It has fewer dependencies and is easier to set up on Windows. + +## Getting Help + +If you encounter issues not covered in this guide: + +1. **Check Git installation:** + ```bash + git --version + bash --version + ``` + +2. **Verify module files exist:** + ```bash + ls -la git_describe.sh + # Should show: -rwxr-xr-x ... git_describe.sh + ``` + +3. **Test the script directly:** + ```bash + bash git_describe.sh + # Should output: {"version": "..."} + ``` + +4. **Check Terraform debug output:** + ```bash + TF_LOG=DEBUG terraform plan 2>&1 | grep -i external + ``` + +5. **Report issues:** + - For module issues: [GitHub Issues](https://github.com/your-org/terraform-git-version/issues) + - For Git Bash issues: [Git for Windows Issues](https://github.com/git-for-windows/git/issues) + +## Summary + +**The key takeaway:** If you're doing Terraform development on Windows, you already have everything you need: + +✅ Git for Windows (required for version control) → includes Git Bash +✅ Terraform CLI (required for infrastructure as code) +❌ No additional dependencies needed + +This module leverages tools you already have installed, making it one of the most Windows-friendly Terraform modules available. From b023194fbaa3f7af59330b6112b65ae8d168fcf0 Mon Sep 17 00:00:00 2001 From: Dino Korah <691011+codemedic@users.noreply.github.com> Date: Mon, 10 Nov 2025 12:06:32 +0000 Subject: [PATCH 4/4] Revise Windows Compatibility Guide for clarity --- WINDOWS.md | 417 +++++++++++++++++++++-------------------------------- 1 file changed, 164 insertions(+), 253 deletions(-) diff --git a/WINDOWS.md b/WINDOWS.md index dfc93fb..42d7397 100644 --- a/WINDOWS.md +++ b/WINDOWS.md @@ -1,361 +1,272 @@ # Windows Compatibility Guide -This document provides comprehensive guidance for using the `terraform-git-version` module on Windows systems. +**TL;DR:** Got Git? You're good to go! 🎉 -## Table of Contents - -- [Quick Start](#quick-start) -- [Prerequisites](#prerequisites) -- [Installation Options](#installation-options) -- [How It Works](#how-it-works) -- [Troubleshooting](#troubleshooting) -- [Frequently Asked Questions](#frequently-asked-questions) -- [Alternative: Using Python](#alternative-using-python) - -## Quick Start - -**TL;DR:** If you have Git installed on Windows (which you need for Terraform development anyway), this module will work without any additional setup. +If you have Git for Windows installed (which you need for Terraform anyway), this module works immediately. No extra setup, no Python, no WSL required. ```bash # In Git Bash (comes with Git for Windows) cd your-terraform-project -terraform init terraform plan ``` -## Prerequisites - -### Required - -| Software | Why It's Required | Typically Installed | -|----------|-------------------|---------------------| -| **Git for Windows** | Provides both the `git` command AND Git Bash shell | ✅ Yes - required for version control | -| **Terraform CLI** | Infrastructure as Code runtime | ✅ Yes - required for Terraform development | +**That's it.** Read on if you need troubleshooting or want to understand why this works. -### Not Required +--- -| Software | Status | -|----------|--------| -| **Python** | ❌ Not needed (removed in v1.2.0+) | -| **WSL/WSL2** | ❌ Not needed (but works if you have it) | -| **Cygwin** | ❌ Not needed (but works if you have it) | -| **MinGW** | ❌ Not needed (but works if you have it) | +## What You Need -## Installation Options +✅ **Git for Windows** - You already have this (required for Terraform development) +✅ **Terraform CLI** - You already have this +❌ **Python** - Not needed anymore! +❌ **WSL** - Not needed (though it works if you have it) +❌ **Cygwin/MinGW** - Not needed (though they work too) -### Option 1: Git Bash (Recommended) +
+📖 Why does this work? (click to expand) -Git Bash is automatically installed with Git for Windows and is the standard environment for Terraform development on Windows. +When you install Git for Windows, you automatically get: -#### Step 1: Install Git for Windows (if not already installed) +- `git.exe` - the Git command +- `bash.exe` - the Bash shell +- Git Bash terminal - a Unix-like environment -1. Download Git for Windows from [https://git-scm.com/download/win](https://git-scm.com/download/win) -2. Run the installer with default settings -3. Git Bash will be installed automatically +This module needs both `git` and `bash` commands. Since Git for Windows bundles them together, you're already set! No Python installation, no WSL setup, no extra steps. -#### Step 2: Verify Installation +
-Open **Git Bash** (not CMD or PowerShell) and run: +--- -```bash -# Check Git is available -git --version -# Expected output: git version 2.x.x.windows.x +## How to Use It -# Check Bash is available -bash --version -# Expected output: GNU bash, version 4.x.x or higher +### Step 1: Open Git Bash -# Check Terraform is available -terraform version -# Expected output: Terraform v1.x.x or higher -``` +Find "Git Bash" in your Start Menu and open it. (It came with Git for Windows) -#### Step 3: Use the Module - -```hcl -# main.tf -module "version" { - source = "github.com/your-org/terraform-git-version" -} - -output "version" { - value = module.version.version -} -``` - -Run in Git Bash: +### Step 2: Run Terraform ```bash -terraform init +cd your-terraform-project terraform plan ``` -**Result:** The module will execute `bash git_describe.sh` which works natively in Git Bash. +**Done!** The module works automatically. + +
+🔧 First time setup? (click if you don't have Git yet) -### Option 2: WSL (Windows Subsystem for Linux) +**Install Git for Windows:** -If you're using WSL for Terraform development, this module works without any changes. +1. Download from [git-scm.com/download/win](https://git-scm.com/download/win) +2. Run installer with default settings +3. Git Bash is installed automatically + +**Verify it works:** ```bash -# In WSL terminal -cd /mnt/c/your-terraform-project -terraform plan +# Open Git Bash and check: +git --version # Should show: git version 2.x.x +bash --version # Should show: GNU bash, version 4.x.x +terraform version # Should show: Terraform v1.x.x ``` -**Note:** Make sure your Terraform project is accessible from WSL. Typically, Windows drives are mounted at `/mnt/c/`, `/mnt/d/`, etc. +
-### Option 3: PowerShell with Git Bash +
+💻 Can I use PowerShell or CMD? (click to expand) -You can use PowerShell as your main terminal and still run Terraform with this module: +**Yes!** All Windows terminals work: -```powershell -# PowerShell will invoke Git Bash for the script execution -terraform plan -``` +- **Git Bash** ✅ Recommended - native bash environment +- **PowerShell** ✅ Works - calls bash.exe automatically +- **CMD** ✅ Works - calls bash.exe automatically +- **WSL** ✅ Works - full Linux environment -**How it works:** When Terraform executes `program = ["bash", "..."]`, Windows will find `bash.exe` from Git for Windows (added to PATH during installation). +When Terraform runs `program = ["bash", "..."]`, Windows finds `bash.exe` from your Git installation (it's in your PATH). You don't need to do anything special. -## How It Works +
-### Execution Flow on Windows +--- -1. **Terraform invokes the external data source:** - ```hcl - data "external" "version" { - program = ["bash", "${path.module}/git_describe.sh", var.version_environment_variable] - } - ``` +## Common Questions -2. **Windows finds bash.exe:** - - Git for Windows adds `C:\Program Files\Git\bin\` to your PATH - - This includes `bash.exe`, `git.exe`, and other Unix tools +### "Do I need to install WSL?" -3. **Bash script executes:** - - Reads environment variable (if specified) - - Runs `git describe --tags --long --dirty --always` - - Returns JSON: `{"version": "..."}` +**No.** Git Bash (included with Git) is enough. WSL works if you already have it, but it's not required. -4. **Terraform parses the JSON output** +### "Do I need Python?" -### Why This Works Seamlessly +**No.** We removed the Python dependency in v1.2.0. This module now uses only Bash and Git - both included with Git for Windows. -- ✅ **Git Bash is included** with Git for Windows (no extra install) -- ✅ **PATH is configured** automatically during Git installation -- ✅ **No credential issues** - uses the same Git credentials as your normal workflow -- ✅ **No WSL overhead** - runs natively on Windows via Git Bash +### "What about AWS credentials or cloud provider setup?" -## Troubleshooting +**Not relevant.** This module doesn't touch AWS, Azure, or any cloud provider. It only: -### Error: "bash: command not found" or "program cannot be found" +- Reads an optional environment variable +- Runs `git describe` to get your version +- Returns the result -**Cause:** Git for Windows is not installed or `bash.exe` is not in your PATH. +Your cloud credentials are handled by Terraform itself, not this module. -**Solution:** +### "Will this work in CI/CD?" -1. Install Git for Windows: [https://git-scm.com/download/win](https://git-scm.com/download/win) -2. Verify PATH includes Git: - ```powershell - # In PowerShell - $env:PATH -split ';' | Select-String 'Git' - # Should show: C:\Program Files\Git\bin or similar - ``` -3. If not in PATH, add it: - - Open "Environment Variables" in Windows - - Add `C:\Program Files\Git\bin` to System PATH - - Restart your terminal +**Yes!** Most Windows CI/CD runners include Git by default: -### Error: "git: command not found" +- ✅ GitHub Actions (Git pre-installed) +- ✅ GitLab CI (Git pre-installed) +- ✅ Azure DevOps (Git pre-installed) +- ✅ Jenkins (install Git on agent) -**Cause:** Git is not installed or not in PATH. +
+📋 Example: GitHub Actions (click to expand) + +```yaml +- name: Setup Terraform + uses: hashicorp/setup-terraform@v2 -**Solution:** Same as above - Git for Windows provides both `bash.exe` and `git.exe`. +- name: Terraform Plan + run: terraform plan + # Works automatically - GitHub Windows runners include Git Bash +``` -### Error: Permission denied +
-**Cause:** The `git_describe.sh` script doesn't have execute permissions. +### "I'm behind a corporate proxy?" -**Solution:** +**No problem.** Configure Git proxy and everything works: ```bash -# In Git Bash -chmod +x git_describe.sh -git add git_describe.sh -git commit -m "Fix permissions" -``` - -Or manually on Windows: -```powershell -# In PowerShell (if needed) -icacls git_describe.sh /grant Everyone:RX +git config --global http.proxy http://proxy.example.com:8080 +git config --global https.proxy http://proxy.example.com:8080 ``` -### Module returns "UNKNOWN" +This module only uses local Git commands anyway - no network calls (unless you're fetching remote tags). -**Cause:** Git cannot find repository information or there are no tags. +--- -**Solutions:** +## Troubleshooting -1. **Check if you're in a Git repository:** - ```bash - git status - # Should NOT show: "fatal: not a git repository" - ``` +### 🚫 Error: "bash: command not found" -2. **Check for Git tags:** - ```bash - git tag - # If empty, create a tag: - git tag -a v1.0.0 -m "Initial version" - ``` +**Fix:** Install Git for Windows from [git-scm.com/download/win](https://git-scm.com/download/win) -3. **Use environment variable override:** - ```hcl - # In your terraform - module "version" { - source = "..." - version_override = "1.0.0" # Bypass Git entirely - } - ``` +
+🔍 Still not working? Check your PATH (click to expand) -### Terminal: CMD vs PowerShell vs Git Bash +```powershell +# In PowerShell, verify Git is in PATH: +$env:PATH -split ';' | Select-String 'Git' +# Should show: C:\Program Files\Git\bin +``` -**Recommendation:** Use **Git Bash** for Terraform commands on Windows. +If missing, add `C:\Program Files\Git\bin` to System PATH: -| Terminal | Works? | Notes | -|----------|--------|-------| -| **Git Bash** | ✅ Yes | Recommended - native bash environment | -| **PowerShell** | ✅ Yes | Works if Git Bash is in PATH | -| **CMD** | ✅ Yes | Works if Git Bash is in PATH | -| **WSL** | ✅ Yes | Full Linux environment | +1. Windows Search → "Environment Variables" +2. Edit "System PATH" +3. Add `C:\Program Files\Git\bin` +4. Restart terminal -## Frequently Asked Questions +
-### Q: Do I need to install WSL? +### 🚫 Module returns "UNKNOWN" -**A:** No. Git Bash (included with Git for Windows) is sufficient. WSL works but is not required. +**Cause:** No Git repository or no tags found. -### Q: Do I need Python? +**Quick fixes:** -**A:** No. As of version 1.2.0+, the Python dependency has been removed. The module now uses Bash exclusively. +```bash +# Check you're in a Git repo: +git status -### Q: What about AWS credentials or cloud provider setup? +# Create a tag if none exist: +git tag v1.0.0 -**A:** This module doesn't interact with cloud providers at all. It only: -- Reads an optional environment variable -- Executes `git describe` to get version information -- Returns the result as JSON +# Or bypass Git entirely: +export TF_MODULE_VERSION=1.0.0 +terraform plan +``` -Your AWS/Azure/GCP credentials are handled by Terraform itself, not by this module. +
+🔧 More troubleshooting options (click to expand) -### Q: Will this work in CI/CD on Windows? +**Check for tags:** -**A:** Yes! Most Windows CI/CD environments (GitHub Actions, GitLab CI, Azure DevOps, Jenkins) include Git and Git Bash by default. +```bash +git tag # Should list tags like v1.0.0 +``` -**Example - GitHub Actions:** -```yaml -- name: Setup Terraform - uses: hashicorp/setup-terraform@v2 +**Use Terraform override:** -- name: Terraform Plan - run: terraform plan - # Works automatically - GitHub Actions Windows runners include Git Bash +```hcl +module "version" { + source = "..." + version_override = "1.0.0" # Bypasses Git +} ``` -### Q: What if I'm behind a corporate proxy? - -**A:** Git proxy configuration works the same way: +**Enable debug logging:** ```bash -# Configure Git proxy (affects both Git and Git Bash) -git config --global http.proxy http://proxy.example.com:8080 -git config --global https.proxy http://proxy.example.com:8080 +TF_LOG=DEBUG terraform plan 2>&1 | grep -i external ``` -This module only uses local Git commands - no network access required (unless fetching remote tags). - -### Q: Can I use this with Terraform Cloud/Enterprise on Windows? +
-**A:** Yes. During the `terraform plan` phase (typically run locally), the module will execute on your local Windows machine using Git Bash. The results are then sent to Terraform Cloud as part of the plan. +### 🚫 Error: Permission denied -If you're running Terraform Cloud agents on Windows, ensure Git is installed on the agent machine. +Rare, but if it happens: -## Alternative: Using Python - -If you prefer to use Python instead of Bash (for example, if you already have Python standardized in your environment), the legacy Python script is still available: +```bash +chmod +x git_describe.sh +``` -### Option: Keep Python Script +--- -1. **Revert main.tf to use Python:** - ```hcl - data "external" "version" { - count = var.version_override == null ? 1 : 0 - program = ["python", "${path.module}/git_describe.py", var.version_environment_variable] - } - ``` +## Still Want to Use Python? -2. **Ensure Python is installed and in PATH:** - ```powershell - # Check Python availability - python --version - # or - python3 --version - ``` +If you have Python standardized in your environment and prefer it: -3. **Install Python if needed:** - - Download from [https://www.python.org/downloads/](https://www.python.org/downloads/) - - During installation, check "Add Python to PATH" +
+🐍 Switch back to Python (click to expand) -### Comparison: Bash vs Python +**Change main.tf to use Python:** -| Aspect | Bash (Default) | Python (Alternative) | -|--------|----------------|---------------------| -| **Installation** | Included with Git | Separate installation required | -| **Configuration** | Automatic (via Git setup) | Must add to PATH manually | -| **Dependencies** | Git only | Git + Python | -| **Windows Support** | Via Git Bash (included) | Via Python installer | -| **Compatibility** | bash 3.2+ (2007+) | Python 2.7+ or 3.x | -| **Maintenance** | Active | Legacy (deprecated) | +```hcl +data "external" "version" { + count = var.version_override == null ? 1 : 0 + program = ["python", "${path.module}/git_describe.py", var.version_environment_variable] +} +``` -**Recommendation:** Unless you have a specific requirement for Python, use the default Bash implementation. It has fewer dependencies and is easier to set up on Windows. +**Ensure Python is installed:** -## Getting Help +```powershell +python --version # or python3 --version +``` -If you encounter issues not covered in this guide: +**Install if needed:** [python.org/downloads](https://www.python.org/downloads/) (check "Add Python to PATH") -1. **Check Git installation:** - ```bash - git --version - bash --version - ``` +**Why Bash is recommended:** -2. **Verify module files exist:** - ```bash - ls -la git_describe.sh - # Should show: -rwxr-xr-x ... git_describe.sh - ``` +| Aspect | Bash (Default) | Python (Alternative) | +|--------|----------------|---------------------| +| Installation | Included with Git | Separate install | +| PATH config | Automatic | Manual | +| Dependencies | Git only | Git + Python | -3. **Test the script directly:** - ```bash - bash git_describe.sh - # Should output: {"version": "..."} - ``` +
-4. **Check Terraform debug output:** - ```bash - TF_LOG=DEBUG terraform plan 2>&1 | grep -i external - ``` +--- -5. **Report issues:** - - For module issues: [GitHub Issues](https://github.com/your-org/terraform-git-version/issues) - - For Git Bash issues: [Git for Windows Issues](https://github.com/git-for-windows/git/issues) +## Bottom Line -## Summary +**You already have everything you need.** Git for Windows = Git + Bash. This module uses both. No extra setup required. -**The key takeaway:** If you're doing Terraform development on Windows, you already have everything you need: +Questions? Problems? Test the script directly: -✅ Git for Windows (required for version control) → includes Git Bash -✅ Terraform CLI (required for infrastructure as code) -❌ No additional dependencies needed +```bash +bash git_describe.sh +# Should output: {"version": "..."} +``` -This module leverages tools you already have installed, making it one of the most Windows-friendly Terraform modules available. +That's all there is to it! 🎉