Clarify script freshness checks

lib/bash/git/README.md

@@ -35,6 +35,8 @@ log_info "Current branch: $branch"
 
 - `git_update_repo` only attempts updates when the checked-out branch is the detected default branch, or an explicit expected branch passed by the caller.
 - `check_script_up_to_date` treats missing git state, untracked scripts, or missing upstreams as skip conditions rather than hard failures.
+- `check_script_up_to_date <script>` compares `HEAD` with the local remote-tracking upstream ref. It does not fetch by default, so the result reflects the freshness of local refs.
+- `check_script_up_to_date --fetch <script>` runs `git fetch --quiet` first, then compares against the refreshed upstream ref. If fetch fails, the helper logs a warning and falls back to local remote-tracking refs.
 
 ## Tests
 

lib/bash/git/lib_git.sh

@@ -267,7 +267,8 @@ git_get_current_branch() {
 #
 # Checks whether a script appears up to date with its git upstream and logs status.
 #
-# @param $1 script_path The path to a script file tracked in a git repo.
+# @param $1 Optional --fetch to refresh remote-tracking refs before comparing.
+# @param $2 script_path The path to a script file tracked in a git repo.
 #
 # Returns:
 #   - 0 if up to date or the check is skipped (no git, no upstream, not a repo).
@@ -276,11 +277,18 @@ git_get_current_branch() {
 #   - 3 if the script has local modifications.
 #
 check_script_up_to_date() {
-    local script_path="$1"
-    if [[ -z "$script_path" ]]; then
-        log_error "Usage: check_script_up_to_date <script_path>"
+    local fetch_before_check=false script_path
+
+    if [[ "${1:-}" == "--fetch" ]]; then
+        fetch_before_check=true
+        shift
+    fi
+
+    if (($# != 1)); then
+        log_error "Usage: check_script_up_to_date [--fetch] <script_path>"
         return 1
     fi
+    script_path="$1"
 
     if [[ ! -e "$script_path" ]]; then
         log_warn "Script '$script_path' not found; skipping latest-version check."
@@ -326,6 +334,16 @@ check_script_up_to_date() {
         return 0
     }
 
+    if [[ "$fetch_before_check" == true ]]; then
+        if git -C "$repo_root" fetch --quiet; then
+            log_info "Fetched upstream state before latest-version check."
+        else
+            log_warn "Unable to fetch upstream state; using local remote-tracking refs."
+        fi
+    else
+        log_info "Using local remote-tracking refs; pass --fetch for a live remote check."
+    fi
+
     behind=$(git -C "$repo_root" rev-list --count HEAD.."$upstream" 2>/dev/null)
     ahead=$(git -C "$repo_root" rev-list --count "$upstream"..HEAD 2>/dev/null)
     if [[ -n "$behind" && "$behind" -gt 0 ]]; then

lib/bash/git/tests/lib_git.bats

@@ -382,6 +382,50 @@ setup() {
     [[ "$output" == *"Repository is up to date with origin/master."* ]]
 }
 
+@test "check_script_up_to_date uses local remote-tracking refs by default" {
+    local other="$TEST_TMPDIR/other"
+    local repo="$TEST_TMPDIR/repo"
+    local remote="$TEST_TMPDIR/remote.git"
+    local script_path="$repo/scripts/tool.sh"
+
+    create_tracked_repo_with_upstream "$repo" "$remote" "scripts/tool.sh" "#!/usr/bin/env bash"
+    git clone "$remote" "$other" >/dev/null 2>&1
+    git -C "$other" config user.name "Bats Test"
+    git -C "$other" config user.email "bats@example.com"
+    printf 'echo remote\n' >> "$other/scripts/tool.sh"
+    git -C "$other" add scripts/tool.sh
+    git -C "$other" commit -m "Update remote script" >/dev/null 2>&1
+    git -C "$other" push origin master >/dev/null 2>&1
+
+    bats_run check_script_up_to_date "$script_path"
+
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"local remote-tracking refs"* ]]
+    [[ "$output" == *"Repository is up to date with origin/master."* ]]
+}
+
+@test "check_script_up_to_date fetches before comparing when requested" {
+    local other="$TEST_TMPDIR/other"
+    local repo="$TEST_TMPDIR/repo"
+    local remote="$TEST_TMPDIR/remote.git"
+    local script_path="$repo/scripts/tool.sh"
+
+    create_tracked_repo_with_upstream "$repo" "$remote" "scripts/tool.sh" "#!/usr/bin/env bash"
+    git clone "$remote" "$other" >/dev/null 2>&1
+    git -C "$other" config user.name "Bats Test"
+    git -C "$other" config user.email "bats@example.com"
+    printf 'echo remote\n' >> "$other/scripts/tool.sh"
+    git -C "$other" add scripts/tool.sh
+    git -C "$other" commit -m "Update remote script" >/dev/null 2>&1
+    git -C "$other" push origin master >/dev/null 2>&1
+
+    bats_run check_script_up_to_date --fetch "$script_path"
+
+    [ "$status" -eq 2 ]
+    [[ "$output" == *"Fetched upstream state before latest-version check."* ]]
+    [[ "$output" == *"Repository is 1 commit(s) behind origin/master"* ]]
+}
+
 @test "check_script_up_to_date returns 3 for a dirty tracked script" {
     local repo="$TEST_TMPDIR/repo"
     local remote="$TEST_TMPDIR/remote.git"