← retour aux snippets

git: ignorer des modifications locales (skip-worktree)

Garder des changements locaux non commités intacts lors des pulls en marquant des fichiers comme skip-worktree.

bash git #git#skip-worktree#ignore#workflow

objectif

Préserver des ajustements locaux (ex: config locale) sans les committer et sans qu’ils soient écrasés par un git pull, en utilisant update-index --skip-worktree. Réversible et ciblé.

code minimal

# marquer un fichier déjà suivi pour ignorer vos changements locaux
git update-index --skip-worktree config/local.env

utilisation

# 1) vérifier quels fichiers sont en skip-worktree
git ls-files -v | awk '$1 ~ /^S/ {print $0}'   # "S" en tête = skip-worktree

# 2) marquer plusieurs fichiers (ex: overrides locaux)
git update-index --skip-worktree \
  config/local.env \
  config/overrides/data.pm.dev.yml

# 3) constater l'effet sur le statut (les changements locaux n'apparaissent plus)
git status -s

# 4) restaurer le comportement normal (réintégrer au suivi)
git update-index --no-skip-worktree config/local.env

# 5) écraser vos modifs locales d'un fichier marqué (forcer la version HEAD)
git checkout -- config/local.env
# ou Git récent:
git restore --source=HEAD --worktree --staged -- config/local.env

# 6) lister précisément les chemins marqués (lecture claire)
git ls-files -v | sed -n 's/^S //p'

variante(s) utile(s)

# ignorer tout un dossier de secrets locaux (sans les retirer du repo)
git ls-files 'secrets/*.env' -z | xargs -0 git update-index --skip-worktree

# forcer un pull sans toucher aux fichiers skip-worktree (les conflits les ignorent)
git pull --ff-only

# rendre vos changements à nouveau visibles pour un commit ponctuel
git update-index --no-skip-worktree config/local.env
git add config/local.env && git commit -m "chore: maj config locale (temporaire)"
git update-index --skip-worktree config/local.env

# détecter des divergences qui empêchent une mise à jour propre
# (si l'upstream modifie un fichier skip-worktree, Git peut le signaler)
git -c advice.skipWorktreeDirty=false status

# alternative moins adaptée: assume-unchanged (pour perf locale, pas pour ignorer des edits durables)
git update-index --assume-unchanged path/to/file
git update-index --no-assume-unchanged path/to/file

notes

  • --skip-worktree s’applique uniquement à des fichiers déjà suivis. Pour des fichiers purement locaux, préférez .gitignore.
  • Si l’amont modifie un fichier marqué, Git peut tenter de mettre à jour le contenu disque; vérifiez après pull.
  • Conservez une liste documentaire des chemins marqués (script d’onboarding) pour éviter les surprises entre machines.
  • Évitez d’utiliser skip-worktree sur des fichiers critiques de build; réservez-le aux configurations locales (ex: config/local.env, overrides/*.yml).