Earth env rename

[gilescope]

Allow to understand EARTH_* env vars as well as EARTHLY_*

(Merge #341 first.)

[github-actions]

🎉 Are we earthbuild yet?

Great progress! You've reduced "earthly" occurrences by 50 (0.89%)

📈 Overall Progress

Branch	Total Count
main	5626
This PR	5576
Difference	-50 (0.89%)

📁 Changes by file type:

File Type	Change
Go files (.go)	❌ +2
Documentation (.md)	✅ -52
Earthfiles	➖ No change

---

Keep up the great work migrating from Earthly to Earthbuild! 🚀

💡 Tips for finding more occurrences

Run locally to see detailed breakdown:

./.github/scripts/count-earthly.sh

Note that the goal is not to reach 0.
There is anticipated to be at least some occurences of earthly in the source code due to backwards compatibility with config files and language constructs.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request focuses on enhancing the flexibility and caching mechanisms within the system. It introduces a new set of environment variables with an EARTH_ prefix, serving as aliases for the existing EARTHLY_ variables, thereby improving naming consistency and future-proofing. Additionally, a significant improvement to caching is made by exposing a content-addressable Git tree hash, which allows for more reliable cache invalidation based on actual content changes rather than commit history. These changes are supported by refactored environment variable lookup utilities and comprehensive documentation updates.

Highlights

• Environment Variable Renaming: Introduced EARTH_* environment variables as aliases for existing EARTHLY_* variables, ensuring backward compatibility while transitioning to a shorter prefix.
• New Git Content Hash: Added EARTH_GIT_CONTENT_HASH (and EARTHLY_GIT_CONTENT_HASH) which provides a content-addressable git tree hash, useful for more stable caching as it only changes when the file tree content changes, not on every commit.
• Refactored Environment Variable Handling: Implemented new utility functions (LookupEnv, IsTrueWithFallback) to streamline the process of checking for both old (EARTHLY_*) and new (EARTH_*) environment variable names.
• Documentation Updates: Updated documentation to reflect the new EARTH_* environment variable names and the introduction of EARTH_GIT_CONTENT_HASH, including guidance on its use for improved caching.

Changelog

• buildcontext/git.go
  • Added contentHash field to resolvedGitProject struct to store the git tree hash.
  • Updated resolveEarthProject to include the new ContentHash in the EarthProject metadata.
  • Modified resolveGitProject to execute git rev-parse HEAD^{tree} and store the content hash.
  • Refactored git metadata file reading into a map for cleaner access.
• cmd/earthly/app/run.go
  • Updated environment variable lookups for EARTHLY_SHOW_HIDDEN and EARTHLY_FULL_TARGET to use envutil.LookupEnv and envutil.IsTrueWithFallback respectively, supporting EARTH_ prefixes.
• cmd/earthly/flag/global.go
  • Modified EnvVars for numerous CLI flags (e.g., installation-name, config, ssh-auth-sock, verbose, debug, pull, push, ci, no-cache, remote-cache) to include EARTH_ prefixed environment variables as alternatives to EARTHLY_.
• cmd/earthly/main.go
  • Updated environment variable lookups for EARTHLY_ENV_FILE, EARTHLY_TARGET_PADDING, and EARTHLY_FULL_TARGET to use envutil.LookupEnv and envutil.IsTrueWithFallback, enabling EARTH_ prefixed alternatives.
• cmd/earthly/subcmd/bootstrap_cmds.go
  • Updated EnvVars for the certs-hostname flag to include EARTH_CERTS_HOSTNAME.
• cmd/earthly/subcmd/build_cmd.go
  • Updated EnvVars for dockerfile, tag, and target flags to include EARTH_ prefixed environment variables.
• cmd/earthly/subcmd/build_flags.go
  • Updated EnvVars for platform, build-arg, secret, secret-file, and cache-from flags to include EARTH_ prefixed environment variables.
• cmd/earthly/subcmd/prune_cmds.go
  • Updated EnvVars for all and reset flags to include EARTH_ prefixed environment variables.
• docs/caching/caching-in-earthfiles.md
  • Updated code block language to Earthfile for consistency.
  • Added a note about EARTH_GIT_CONTENT_HASH as a more stable alternative to EARTH_GIT_HASH for caching purposes.
• docs/earthfile/builtin-args.md
  • Added EARTH_GIT_CONTENT_HASH to the table of git-related arguments with its description and example value.
  • Updated the table to use EARTH_ prefixes for all git-related arguments, while implicitly supporting EARTHLY_ for backward compatibility.
  • Adjusted formatting for hint blocks and tables.
• util/envutil/is_true.go
  • Added LookupEnv function to retrieve environment variables with a fallback mechanism for new and old keys.
  • Added IsTrueWithFallback function to check for truthy environment variable values with fallback support.
• util/gitutil/detectgit.go
  • Added ErrCouldNotDetectGitContentHash error constant.
  • Added ContentHash field to the GitMetadata struct.
  • Implemented detectGitContentHash function to retrieve the git tree hash.
  • Refactored detectGitHash and detectGitShortHash to use a common gitRevParse helper function for improved code reuse.
• util/gitutil/detectgit_test.go
  • Added a new test case TestDetectGitContentHash to verify the correct detection and stability of the git content hash across commits and amends.
• variables/builtin.go
  • Added EARTH_ prefixed aliases for various built-in arguments such as EARTH_TARGET, EARTH_TARGET_PROJECT, EARTH_PUSH, EARTH_CI, EARTH_VERSION, EARTH_BUILD_SHA, EARTH_LOCALLY, and all EARTH_GIT_* arguments, including the new EARTH_GIT_CONTENT_HASH.
• variables/builtin_test.go
  • Added TestBuiltinArgsContentHash to verify that EARTH_GIT_CONTENT_HASH is correctly populated when git metadata is available.
  • Added TestBuiltinArgsContentHashNilGitMeta to ensure EARTH_GIT_CONTENT_HASH is not found when git metadata is nil.
• variables/reserved/names.go
  • Defined new constants for EARTH_ prefixed environment variable names for all relevant built-in arguments.
  • Added the new EARTH_ prefixed constants to the args map for internal tracking.

Activity

• The pull request description indicates a dependency on another pull request (Add content hash support + support EARTH_GIT_* builtins #341) which should be merged first.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces support for EARTH_* environment variables as aliases for the existing EARTHLY_* variables, ensuring backward compatibility. This is achieved consistently across the codebase by prioritizing the new EARTH_* variables. Additionally, a new git-related built-in argument, EARTH_GIT_CONTENT_HASH, is introduced. This represents the git tree hash, which is more stable for caching purposes than the commit hash. The implementation includes helpful refactorings, such as in buildcontext/git.go and util/gitutil/detectgit.go, to reduce code duplication, and is well-tested. The documentation has also been updated accordingly. My main feedback is a suggestion to reduce code duplication in variables/builtin.go where both new and old variables are being set.

[gemini-code-assist]

This function now contains a significant amount of duplicated code to add both the new EARTH_* and old EARTHLY_* variables. To improve maintainability and readability, consider introducing a helper function to handle adding both variables at once.

For example:

func addWithAlias(s *Scope, new, old, val string) {
    s.Add(new, val)
    s.Add(old, val)
}

You could then replace pairs of ret.Add(...) calls with a single call to this helper, like:

addWithAlias(ret, arg.EarthGitHash, arg.EarthlyGitHash, gitMeta.Hash)
addWithAlias(ret, arg.EarthGitShortHash, arg.EarthlyGitShortHash, gitMeta.ShortHash)

This would make the code much cleaner and easier to manage, especially if more aliased variables are added in the future.

[kmannislands]

Should we update docs in the same pass? Hopefully can be mostly LLM'd

Docs updated in base branch: https://github.com/EarthBuild/earthbuild/pull/341/changes#diff-a08415d10d04e498b9f32bd0057aa2a077391fb3f09f0c569c3d7577c1704364

Should be coherent once this is rebased after that merges

[kmannislands]

I think we should update this to just take newKey and infer oldKey or visa-versa.

Also this seems the right place to hook in for warn logging if the old naming is used

[kmannislands]

I think this PR should set base to the giles-content branch so we see the right change set here