glab cli environment variable deprecation (GLAB_ prefix) feedback issue

Summary

This issue is used to track the progress of deprecating current environment variables that are used by the glab cli.

Starting with glab version v2.0.0 environment variables used by glab should be prefixed with GLAB_, namely:

  • GLAMOUR_STYLE
  • DEBUG
  • NO_PROMPT
  • FORCE_HYPERLINKS

The following environment variables that will continue working as before are:

  • BROWSER - the process spawned by the command to start the browser inherits the environment variables, so it doesn't make sense to have GLAB_BROWSER to rename it to BROWSER
  • NO_COLOR - the tool follows the https://no-color.org/ specification
  • VISUAL - considered one of the default values nowadays
  • EDITOR - considered one of the default values nowadays

Until then both versions of the environment variables will work. To give an example:

❯ GLAB_NO_PROMPT=true ./bin/glab mr create
ERROR: --title or --fill required for non-interactive mode.
Try 'glab mr create --help' for more information.

❯ NO_PROMPT=true ./bin/glab mr create
DEPRECATION WARNING: The environment variable NO_PROMPT has been deprecated and will be removed in future releases. Use GLAB_NO_PROMPT instead.
ERROR: --title or --fill required for non-interactive mode.
Try 'glab mr create --help' for more information.

To give another couple of examples:

❯ GLAMOUR_STYLE=light ./bin/glab issue view 7928 | head -3
DEPRECATION WARNING: The environment variable GLAMOUR_STYLE has been deprecated and will be removed in future releases. Use GLAB_GLAMOUR_STYLE instead.
title:	glab release fails with 422 when using --publish-to-catalog
state:	open

❯ GLAB_GLAMOUR_STYLE=light ./bin/glab issue view 7928 | head -3
title:	glab release fails with 422 when using --publish-to-catalog
state:	open
author:	ignacio.piqueras

Below is the list of environment variables and their new names:

before after
GLAMOUR_STYLE GLAB_GLAMOUR_STYLE
DEBUG GLAB_DEBUG
NO_PROMPT GLAB_NO_PROMPT
FORCE_HYPERLINKS GLAB_FORCE_HYPERLINKS

Implementation plan

Note: This plan was drafted during an AI-assisted triage of the backlog and has not been validated by a maintainer. Treat it as a starting point: file paths, line numbers, and the approach may need adjusting.

  1. In internal/run/run.go, add an unexported debugEnabled() helper next to cmdWithStderr. It should return true when either GLAB_DEBUG or DEBUG parses as a truthy bool via strconv.ParseBool, checking GLAB_DEBUG first. Note that internal/utils imports internal/run, so run cannot call utils.IsEnvVarEnabled: keep the helper local to the package.
  2. When only the legacy DEBUG is set, print DEPRECATION WARNING: The environment variable DEBUG has been deprecated and will be removed in future releases. Use GLAB_DEBUG instead. to os.Stderr, guarded by a package-level sync.Once so a command that shells out to Git repeatedly warns once rather than per invocation. Match the wording in internal/utils/utils.go:233.
  3. Replace both inline strconv.ParseBool(os.Getenv("DEBUG")) checks, in cmdWithStderr.Output (internal/run/run.go:39) and cmdWithStderr.Run (internal/run/run.go:55), with a call to the new helper.
  4. Add internal/run/run_test.go (the package has no test file yet). Use t.Setenv to cover four cases: GLAB_DEBUG=true traces, DEBUG=true traces and warns, both set warns once, neither set is silent. Assert on a captured os.Stderr, following the stderr-capture pattern in internal/commands/root_test.go:52 (TestDeprecationWarningStaysOffStdOut).
  5. No help text changes, so make gen-docs is not needed. docs/source/configuration.md:134 already claims GLAB_DEBUG covers underlying Git commands, and this change makes that true.
  6. Run go test ./internal/run/... ./internal/utils/... ./cmd/glab/... and make lint.
Edited by Kai Armstrong