---
name: git_push_if_ahead
kind: function
lang: bash
domain: infra
version: "1.0.0"
purity: impure
signature: "git_push_if_ahead(repo_dir: string) -> stdout: status line"
description: "Decide si pushear un repo git usando solo refs locales (sin tocar la red para decidir). Sin upstream hace push -u; con upstream y ahead > 0 pushea; con 0 ahead salta. Si el push falla no aborta — emite [error] y exit 0."
tags: [git, push, infra, ahead, upstream]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: repo_dir
    desc: "path al repo git a evaluar; default '.'"
output: "linea de estado por stdout: '[push -u] repo (branch)', '[push] repo (branch, N commits ahead)', '[skip] repo (up-to-date)' o '[error] repo: razon'"
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/infra/git_push_if_ahead.sh"
---

## Ejemplo

```bash
source bash/functions/infra/git_push_if_ahead.sh

# Pushear si hay commits locales
status=$(git_push_if_ahead $HOME/fn_registry)
echo "$status"
# [push] fn_registry (master, 3 commits ahead)
# o:
# [skip] fn_registry (up-to-date)

# Iterar sobre multiples repos
while IFS= read -r repo; do
    git_push_if_ahead "$repo"
done < <(discover_git_repos $HOME/fn_registry)
```

## Estados de salida

| Linea stdout | Significado |
|---|---|
| `[push -u] repo (branch)` | Sin upstream — se hizo push -u origin |
| `[push] repo (branch, N ahead)` | Tenia commits locales — se pusheo |
| `[skip] repo (up-to-date)` | 0 ahead localmente — no se toco la red |
| `[error] repo: razon` | Push rechazo (non-fast-forward, etc.) — se reporta pero exit 0 |

## Notas

`rev-list --count @{u}..HEAD` solo lee refs locales, no hace fetch. Esto es correcto para un push-only workflow: si en otro PC se hizo push, aqui no tenemos nada local que pushear de todas formas. El error `[error]` tipicamente indica que la rama remote esta adelante — el caller debe sugerir `/full-git-pull`.