From a1a10c777f8389d2a6997556bf96f0673de35d40 Mon Sep 17 00:00:00 2001
From: foxfromworld <foxfromworld@gmail.com>
Date: Thu, 5 Mar 2026 13:55:05 +0800
Subject: [PATCH] =?UTF-8?q?Docs:=20clarify=20PATH=20requirement=20and=20ex?=
 =?UTF-8?q?plain=20highlighted=20outputs=20(Fixes=E2=80=A6=20(#3610)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Docs: clarify PATH requirement and explain highlighted outputs (Fixes #2376)

* Update CHANGELOG for PR #3610

* Apply suggestion from @keith-hall

Applied reviewer’s suggestion to improve PATH export: safer with quotes and more convenient with $(pwd).

Co-authored-by: Keith Hall <keith-hall@users.noreply.github.com>

* Docs: clarify PATH setup in CONTRIBUTING.md, remove that section from README.md

* Docs: add cross reference to syntax tests step 5 in doc/assets.md

---------

Co-authored-by: Keith Hall <keith-hall@users.noreply.github.com>
---
 CHANGELOG.md    |  1 +
 CONTRIBUTING.md | 26 ++++++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 04bb52ce..37f435d3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,7 @@
 # unreleased
 
 - Fixed bug caused by using `--plain` and `--terminal-width=N` flags simultaneously, see #3529 (@H4k1l)
+- Fixed syntax tests path, see #3610 (@foxfromworld)
 
 ## Features
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 591bce7b..3852a755 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -91,3 +91,29 @@ To learn how to write regression tests for theme and syntax changes, read the
 [Syntax
 tests](https://github.com/sharkdp/bat/blob/master/doc/assets.md#syntax-tests)
 section in `assets.md`.
+
+### Ensuring bat is available for Syntax tests
+
+The syntax test script (`tests/syntax-tests/update.sh`) calls `bat` from your PATH and regenerates the highlighted output files under
+`tests/syntax-tests/highlighted/`. These files are used to verify that syntax highlighting works as expected.
+
+- If you only built the binaries with:
+  ```bash
+  cargo build --bins
+  ```
+
+  you need to add the debug build to your PATH from the bat project root before running the tests.
+  See also step 5 in [Syntax
+tests](https://github.com/sharkdp/bat/blob/master/doc/assets.md#syntax-tests) for related instructions.
+  ```bash
+  export PATH="$PATH:$(pwd)/target/debug"
+  ```
+  Otherwise, you will see:
+  ```bash
+  Error: Could not execute 'bat'. Please make sure that the executable is available on the PATH.
+  ```
+- If you installed bat with:
+  ```bash
+  cargo install --path . --locked
+  ```
+  then bat will be available in ~/.cargo/bin (usually already in PATH), and the tests will run without issues.
\ No newline at end of file