Document color and link output behavior for v2.15.1 #18
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -131,7 +131,7 @@ pushed: | |
| ```yaml title=".pre-commit-config.yaml" | ||
| repos: | ||
| - repo: https://github.com/commit-check/commit-check | ||
| rev: v2.15.1 | ||
| hooks: | ||
| - id: check-no-force-push | ||
| stages: [pre-push] | ||
|
|
@@ -190,6 +190,22 @@ and how CLI, environment and file settings override each other. | |
| $ commit-check -m --dry-run | ||
| ``` | ||
|
|
||
| ### Color and links | ||
|
|
||
| Output adapts to where it is going. A terminal gets ANSI color, and on | ||
| terminals that render OSC 8 hyperlinks the rule ID is itself a link to its | ||
| documentation. Piped or redirected output — a CI log, a file — gets plain | ||
| text with a `Docs:` line instead, so nothing is lost and no escape codes | ||
| leak into places that read them as noise. | ||
|
|
||
| To override the detection: | ||
|
|
||
| | Variable | Effect | | ||
| | --- | --- | | ||
| | `NO_COLOR=1` | no color, wherever it runs ([no-color.org](https://no-color.org)) | | ||
| | `FORCE_COLOR=1` / `FORCE_COLOR=0` | color on or off, outranking everything else | | ||
| | `FORCE_HYPERLINK=1` / `FORCE_HYPERLINK=0` | linked rule IDs on or off | | ||
|
Comment on lines
+201
to
+207
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
# Expect implementation and tests to define accepted values and precedence.
rg -n -C 6 --glob '!docs/**' --glob '!*.md' \
'\b(NO_COLOR|FORCE_COLOR|FORCE_HYPERLINK)\b' .Repository: commit-check/commit-check.com Length of output: 167 🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '--- candidate files ---'
git ls-files | rg '(^|/)(docs/example\.md|AGENTS\.md|package\.json|.*\.(ts|js|tsx|jsx|rs|go|py))$' | head -200
printf '%s\n' '--- relevant references, including documentation and hidden files ---'
rg -n -C 8 --hidden \
--glob '!node_modules/**' --glob '!dist/**' --glob '!build/**' \
'\b(NO_COLOR|FORCE_COLOR|FORCE_HYPERLINK)\b' .Repository: commit-check/commit-check.com Length of output: 4581 🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '--- docs/example.md: color and links section ---'
sed -n '175,210p' docs/example.md
printf '%s\n' '--- docs/changelog.md: related release entry ---'
sed -n '29,45p' docs/changelog.md
printf '%s\n' '--- documentation checks and site hooks ---'
sed -n '1,240p' tests/docs_sync_test.py
sed -n '1,260p' scripts/mkdocs_hooks.py
printf '%s\n' '--- repository file inventory ---'
git ls-files | sed -n '1,240p'Repository: commit-check/commit-check.com Length of output: 17731 🌐 Web query:
💡 Result: These environment variables are used to control the output styling of command-line interface (CLI) tools, specifically regarding the inclusion of ANSI escape sequences for color and OSC 8 sequences for hyperlinks. NO_COLOR This is a standardized environment variable that, when present and not empty, instructs a CLI tool to disable all colored output [1]. It is widely adopted by various terminal-based applications and libraries [1][2][3][4]. The specification suggests that tools should prioritize user configuration (e.g., CLI flags or config files) over this variable, but if a tool respects it, the presence of NO_COLOR should override default color detection [2][3]. FORCE_COLOR This environment variable is used to force-enable colored output even when the tool would otherwise disable it, such as when the output is being piped or redirected to a non-TTY (non-interactive) destination [1][5]. The standard practice for implementations is that if the variable is present and non-empty, the tool should force the inclusion of ANSI color codes [1][5]. It is common for tools to treat FORCE_COLOR as an override that takes precedence over platform heuristics (like checking if stdout is a TTY) but is generally overridden by NO_COLOR [1][2][3]. FORCE_HYPERLINK Similar to FORCE_COLOR, this variable is used to force the emission of OSC 8 hyperlink sequences, which allow terminals to display clickable links [3][6]. While there is no single universal "FORCE_HYPERLINK" standard as widespread as NO_COLOR, many CLI tools and libraries have implemented it to allow users to opt-in to hyperlink support in environments where the tool's auto-detection (often based on terminal capabilities) might otherwise disable them [7][6][8]. Implementation Strategy When implementing support for these variables in a CLI tool, the recommended pattern is: 1. Check for the disabling variable (NO_COLOR) first [1][2]. 2. Check for the forcing variable (FORCE_COLOR / FORCE_HYPERLINK) next [1][2][3]. 3. Apply platform-based auto-detection (e.g., isatty(stdout)) as a fallback only if no override variables are set [2][7][3]. 4. Respect explicit command-line flags (e.g., --color or --no-color) as the highest priority override before checking these environment variables [1][2][3]. Note on Commit-Check Regarding the specific tool "commit-check," its documentation does not list FORCE_HYPERLINK, FORCE_COLOR, or NO_COLOR as primary configuration features [9][10]. Instead, it uses a TOML-based configuration (cchk.toml or commit-check.toml) for behavior management [9][10]. It focuses on Git-specific validation logic (such as blocking force pushes via --no-force-push or CCHK_ALLOW_FORCE_PUSH) rather than terminal output styling [9][10]. Citations:
🏁 Script executed: #!/bin/bash
set -euo pipefail
python3 - <<'PY'
import json
import urllib.request
from urllib.error import HTTPError
urls = [
"https://api.github.com/repos/commit-check/commit-check",
"https://api.github.com/repos/commit-check/commit-check/git/trees/HEAD?recursive=1",
]
for url in urls:
print(f"--- {url} ---")
try:
with urllib.request.urlopen(url, timeout=20) as response:
data = json.load(response)
if "tree" in data:
for item in data["tree"]:
path = item.get("path", "")
if any(token in path.lower() for token in ("color", "output", "terminal", "ansi", "hyper")):
print(path)
else:
print(json.dumps({
key: data.get(key)
for key in ("full_name", "default_branch", "html_url")
}, indent=2))
except HTTPError as exc:
print(f"HTTP {exc.code}: {exc.read().decode('utf-8', 'replace')[:500]}")
PYRepository: commit-check/commit-check.com Length of output: 2517 🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '--- upstream links in repository metadata ---'
rg -n -i 'github\.com|repository|commit-check' README.md mkdocs.yml docs/index.md docs/getting-started.md docs/changelog.md | head -120
printf '%s\n' '--- GitHub repository candidates ---'
for repo in commit-check/commit-check commit-check/commit-check.com; do
printf '%s\n' "--- $repo ---"
curl -ksS --max-time 20 "https://api.github.com/repos/$repo" |
python3 -c 'import json,sys; d=json.load(sys.stdin); print({k:d.get(k) for k in ("full_name","default_branch","html_url","message")})'
doneRepository: commit-check/commit-check.com Length of output: 12571 🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '--- upstream refs ---'
git ls-remote --heads --tags https://github.com/commit-check/commit-check.git 2>&1 | head -80
printf '%s\n' '--- public source search page ---'
curl -ksS --max-time 20 \
'https://github.com/commit-check/commit-check/search?q=FORCE_HYPERLINK&type=code' |
rg -o '.{0,120}(FORCE_HYPERLINK|code search|Sign in).{0,180}' | head -20 || trueRepository: commit-check/commit-check.com Length of output: 4936 🏁 Script executed: #!/bin/bash
set -euo pipefail
url='https://codeload.github.com/commit-check/commit-check/tar.gz/90ace064c5be9b089013833bcb1ec993ff304d4b'
printf '%s\n' '--- source paths related to output styling ---'
curl -ksSL --max-time 30 "$url" |
tar -tzf - |
rg -i '(color|hyper|ansi|output|terminal|console)' |
head -100
printf '%s\n' '--- exact environment-variable references in the source archive ---'
curl -ksSL --max-time 30 "$url" |
tar -xzf - -O 2>/dev/null |
rg -n -C 8 '\b(NO_COLOR|FORCE_COLOR|FORCE_HYPERLINK)\b' || trueRepository: commit-check/commit-check.com Length of output: 214 🏁 Script executed: #!/bin/bash
set -u
url='https://codeload.github.com/commit-check/commit-check/tar.gz/90ace064c5be9b089013833bcb1ec993ff304d4b'
printf '%s\n' '--- archive response ---'
curl -ksSIL --max-time 30 "$url" | head -30
printf '%s\n' '--- archive listing ---'
archive="$(mktemp)"
trap 'rm -f "$archive"' EXIT
if curl -ksSL --max-time 30 "$url" -o "$archive"; then
file "$archive"
tar -tzf "$archive" 2>&1 | head -120
else
printf '%s\n' 'archive download failed'
fiRepository: commit-check/commit-check.com Length of output: 5558 🏁 Script executed: #!/bin/bash
set -euo pipefail
python3 - <<'PY'
import io
import tarfile
import urllib.request
url = "https://codeload.github.com/commit-check/commit-check/tar.gz/90ace064c5be9b089013833bcb1ec993ff304d4b"
request = urllib.request.Request(url, headers={"User-Agent": "read-only-source-inspection"})
with urllib.request.urlopen(request, timeout=30) as response:
archive = response.read()
with tarfile.open(fileobj=io.BytesIO(archive), mode="r:gz") as tar:
matches = []
for member in tar.getmembers():
if not member.isfile() or not member.name.endswith(".py"):
continue
text = tar.extractfile(member).read().decode("utf-8", "replace")
if any(name in text for name in ("NO_COLOR", "FORCE_COLOR", "FORCE_HYPERLINK")):
matches.append((member.name, text))
print("--- matching files ---")
for name, text in matches:
print(name)
lines = text.splitlines()
for number, line in enumerate(lines, 1):
if any(token in line for token in ("NO_COLOR", "FORCE_COLOR", "FORCE_HYPERLINK")):
start = max(1, number - 12)
end = min(len(lines), number + 18)
print("\n".join(f"{i:4}: {lines[i-1]}" for i in range(start, end + 1)))
print("---")
PYRepository: commit-check/commit-check.com Length of output: 2453 🏁 Script executed: #!/bin/bash
set -euo pipefail
python3 - <<'PY'
import io
import ssl
import tarfile
import urllib.request
url = "https://codeload.github.com/commit-check/commit-check/tar.gz/90ace064c5be9b089013833bcb1ec993ff304d4b"
context = ssl._create_unverified_context()
request = urllib.request.Request(url, headers={"User-Agent": "read-only-source-inspection"})
with urllib.request.urlopen(request, context=context, timeout=30) as response:
archive = response.read()
with tarfile.open(fileobj=io.BytesIO(archive), mode="r:gz") as tar:
matches = []
for member in tar.getmembers():
if not member.isfile() or not member.name.endswith(".py"):
continue
text = tar.extractfile(member).read().decode("utf-8", "replace")
if any(name in text for name in ("NO_COLOR", "FORCE_COLOR", "FORCE_HYPERLINK")):
matches.append((member.name, text))
print("--- matching files ---")
if not matches:
print("No Python source or test file contains the queried variables.")
for name, text in matches:
print(name)
lines = text.splitlines()
for number, line in enumerate(lines, 1):
if any(token in line for token in ("NO_COLOR", "FORCE_COLOR", "FORCE_HYPERLINK")):
start = max(1, number - 12)
end = min(len(lines), number + 18)
print("\n".join(f"{i:4}: {lines[i-1]}" for i in range(start, end + 1)))
print("---")
PYRepository: commit-check/commit-check.com Length of output: 43158 Document the complete output override semantics.
🤖 Prompt for AI Agents |
||
|
|
||
| ### Checking a range of commits | ||
|
|
||
| `--rev` makes each commit addressable without checking it out or piping its | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Qualify default output behavior in both documentation locations. Explicit environment-variable overrides make the current unconditional wording inaccurate.
docs/changelog.md#L14-L14: prefix the highlight with “By default” and reference the override variables.docs/example.md#L195-L199: state that terminal detection applies by default and that explicit overrides take precedence.🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 14-14: Link fragments should be valid
(MD051, link-fragments)
📍 Affects 2 files
docs/changelog.md#L14-L14(this comment)docs/example.md#L195-L199🤖 Prompt for AI Agents