Git
Français ▾ Topics ▾ Latest version ▾ git-worktree last updated in 2.44.0

NOM

git-worktree - Gérer plusieurs arbres de travail

SYNOPSIS

git worktree add [-f] [--detach] [--checkout] [--lock] [-b <nouvelle-branche>] <chemin> [<commit-esque>]
git worktree list [--porcelain]
git worktree lock [--reason <chaîne>] <arbre-de-travail>
git worktree move <arbre-de-travail> <nouveau-chemin>
git worktree prune [-n] [-v] [--expire <expire>]
git worktree remove [-f] <arbre-de-travail>
git worktree unlock <arbre-de-travail>

DESCRIPTION

Gère plusieurs arbres de travail rattachés au même dépôt.

Un dépôt git peut prendre en charge plusieurs arbres de travail, ce qui vous permet de consulter plus d’une branche à la fois. Avec git worktree add, un nouvel arbre de travail est associé au dépôt. Ce nouvel arbre de travail est appelé "arbre de travail lié" par opposition à l'"arbre de travail principal" préparé par "git init" ou "git clone". Un dépôt a un arbre de travail principal (s’il ne s’agit pas d’un dépôt nu) et zéro ou plusieurs arbres de travail liés. Lorsque vous avez terminé avec un arbre de travail lié, supprimez-le avec git worktree remove.

Si un arbre de travail est supprimé sans utiliser git worktree remove, alors les fichiers administratifs associés, qui résident dans le dépôt (voir "DÉTAILS" ci-dessous), seront éventuellement supprimés automatiquement (voir gc.worktreePruneExpire dans git-config[1]), ou vous pouvez exécuter git worktree prune dans l’arbre de travail principal ou dans tout autre arbre de travail lié pour nettoyer les fichiers administratifs périmés.

Si un arbre de travail lié est stocké sur un support mobile ou un partage réseau qui n’est pas toujours monté, vous pouvez empêcher l’élagage de ses fichiers administratifs en lançant la commande git worktree lock, en spécifiant éventuellement --reason pour expliquer pourquoi l’arbre de travail est verrouillé.

COMMANDES

ajouter <chemin> [<commit-esque>]

Créer <chemin> et valider <commit-esque> dans celui-ci. Le nouveau répertoire de travail est lié au dépôt actuel, partageant tout sauf les fichiers spécifiques au répertoire de travail tels que HEAD, index, etc. - peut aussi être spécifié comme <commit-esque> ; il est synonyme de @{-1}.

Si le <commit-esque> est un nom de branche (appelons-le <branche>) et n’est pas trouvé, et ni -b ni -B ni --detach ne sont utilisés, mais qu’il existe une branche de suivi dans exactement un dépôt distant (appelons-le <distant>) avec un nom correspondant, le traiter comme équivalent à :

$ git worktree add --track -b <branche> <chemin> <distant>/<branche>

Si la branche existe dans plus d’un distant et que l’un d’entre eux est la valeur de la variable de configuration checkout.defaultRemote, celui-ci sera utilisé pour désambiguïser, même si la <branche> n’est pas unique parmi tous les distants. Réglez la variable checkout.defaultRemote=origin par exemple pour extraire toujours les branches distantes depuis celle-ci si <branche> est ambigüe mais existe sur le distant origin. Voir aussi checkout.defaultRemote dans git-config[1].

Si <commit-esque> est omis et que ni -b ni -B ni --detach ne sont utilisés, alors, par commodité, le nouvel arbre de travail est associé à une branche (appelez-la <branche>) nommée d’après $(basename <chemin>). Si <branche> n’existe pas, une nouvelle branche basée sur HEAD est automatiquement créée comme si -b <branche> était donné. Si <branche> existe, elle sera extraite dans le nouvel arbre de travail, si elle n’est pas extraite ailleurs, sinon la commande refusera de créer l’arbre de travail (à moins que --force soit utilisé).

list

Lister les détails de chaque arbre de travail. L’arbre de travail principal est listé en premier, suivi de chacun des arbres de travail liés. Les détails de sortie comprennent si l’arbre de travail est vide, la révision en cours et la branche en cours (ou "HEAD détachée" s’il n’y en a pas).

lock

Si un arbre de travail se trouve sur un support amovible ou un partage réseau qui n’est pas toujours monté, le verrouiller pour éviter que ses fichiers administratifs ne soient élagués automatiquement. Cela permet également d’éviter qu’il soit déplacé ou supprimé. Si vous le souhaitez, vous pouvez spécifier une raison pour le verrouillage avec "--reason".

move

Déplacer un arbre de travail vers une nouvelle place. Notez que l’arbre de travail principal ou les arbres de travail liés contenant des sous-modules ne peuvent pas être déplacés.

prune

Élaguer les informations de l’arbre de travail dans $GIT_DIR/worktrees.

remove

Supprimer un arbre en état de marche. Seules les arbres de travail propres (pas de fichiers non suivis et pas de modification dans les fichiers suivis) peuvent être supprimés. Les arbres de travail non propres ou ceux qui comportent des sous-modules peuvent être supprimés avec ---force. L’arbre de travail principal ne peut pas être supprimé.

unlock

Déverrouiller un arbre de travail, ce qui permet de l’élaguer, de le déplacer ou de le supprimer.

OPTIONS

-f
--force

Par défaut, add refuse de créer un nouvel arbre de travail lorsque <commit-esque> est un nom de branche et est déjà extrait par un autre arbre de travail, ou si <chemin> est déjà assigné à un arbre de travail mais est manquant (par exemple, si <chemin> a été supprimé manuellement). Cette option annule ces protections. Pour ajouter un chemin d’arbre de travail manquant mais verrouillé, spécifiez --force deux fois.

move refuse de déplacer un arbre de travail verrouillé à moins que --force ne soit spécifiée deux fois. Si la destination est déjà assignée à un autre arbre de travail mais est manquante (par exemple, si <nouveau-chemin> a été supprimé manuellement), alors --force permet au déplacement de continuer ; utilisez --force deux fois si la destination est verrouillée.

remove refuse de supprimer un arbre de travail sale à moins que --force ne soit utilisé. Pour supprimer un arbre de travail verrouillé, il faut spécifier deux fois -- force.

-b <nouvelle-branche>
-B <nouvelle-branche>

Avec add, créer une nouvelle branche nommée <nouvelle-branche> commençant à <commit-esque>, et extraire <nouvelle-branche> dans le nouvel arbre de travail. Si <commit-esque> est omis, la valeur par défaut est HEAD. Par défaut, -b refuse de créer une nouvelle branche si elle existe déjà. -B annule cette protection, en remettant <nouvelle-branche> à <commit-esque>.

--detach

Avec add, détacher HEAD dans le nouvel arbre de travail. Voir "HEAD DÉTACHÉE" dans git-checkout[1].

--[no-]checkout

Par défaut, add`extrait `<commit-esque>, cependant, --no-checkout peut être utilisé pour annuler l’extraction afin de permettre des personnalisations, telles que la configuration de l’extraction partielle. Voir "Extraction partielle" dans git-read-tree[1].

--[no-]guess-remote

Avec worktree add <chemin>, sans <commit-esque>, au lieu de créer une nouvelle branche à partir de HEAD, s’il existe une branche de suivi d’exactement un distant correspondant au basename de <chemin>, baser la nouvelle branche sur la branche de suivi à distance, et marquer la branche de suivi à distance comme étant "amont" de la nouvelle branche.

Cela peut également être configuré comme le comportement par défaut en utilisant l’option de configuration worktree.guessRemote.

--[no-]track

À la création d’une nouvelle branche, si <commit-esque>`est une branche, la marquer comme « upstream » amont de la nouvelle branche. C'est la valeur par défaut si `<commit-esque> est une branche de suivi à distance. Voir « --track » dans git-branch[1] pour plus de détails.

--lock

Garder l’arbre de travail verrouillé après la création. C’est l’équivalent de git worktree lock après git worktree add, mais sans condition de compétition.

-n
--dry-run

Avec prune, ne rien supprimer ; montrer seulement ce qui serait supprimé.

--porcelain

Avec list, donner la sortie dans un format facile à analyser par script. Ce format restera stable à travers les versions de Git et sans tenir compte de la configuration utilisateur. Voir ci-dessous pour de plus amples détails.

-q
--quiet

Avec add, supprimer les messages d’état.

-v
--verbose

Avec prune, signaler toutes les suppressions.

--expire <date>

Avec prune, n’expirer que les arbres de travail inutilisés plus vieux que <temps>.

--reason <chaîne>

Avec lock, une explication de la raison pour laquelle l’arbre de travail est verrouillé.

<arbre-de-travail>

Les arbres de travail peuvent être identifiés par leur chemin, qu’il soit relatif ou absolu.

Si le dernier élément du chemin de l’arbre de travail est unique parmi les arbres de travail, il peut être utilisé pour identifier les arbres de travail. Par exemple, si vous n’avez que deux arbres de travail, à "/abc/def/ghi" et "/abc/def/ggg", alors "ghi" ou "def/ghi" suffit à indiquer le premier arbre de travail.

RÉFS

Dans le cas de plusieurs arbres de travail, certaines réfs peuvent être partagées entre tous les arbres de travail, certaines réfs sont locales. Par exemple, HEAD est différente pour tous les arbres de travail. Cette section concerne les règles de partage et la manière d’accéder aux références d’un arbre de travail à partir d’un autre.

En général, toutes les pseudo réfs sont par arbre de travail et toutes les réfs commençant par "refs/" sont partagées. Les pseudo réfs sont celles comme HEAD qui sont directement sous GIT_DIR au lieu d’être à l’intérieur de GIT_DIR/refs. Il y a une exception à cela : les réfs à l’intérieur de refs/bisect et refs/worktree ne sont pas partagées.

Les références par arbre de travail sont toujours accessibles à partir d’un autre arbre de travail via deux chemins spéciaux, l’arbre principal et les arbres de travail. Le premier donne accès aux références par arbre de travail de l’arbre de travail principal, tandis que le second donne accès à tous les arbres de travail liés.

Par exemple, arbre-de-travail-principal/HEAD ou arbre-de-travail-principal/refs/bisect/good ont la même valeur que la HEAD de l’arbre de travail principal et refs/bisect/good respectivement. De même, worktrees/foo/HEAD ou worktrees/bar/refs/bisect/bad sont les mêmes que GIT_COMMON_DIR/worktrees/foo/HEAD et GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad.

Pour accéder aux réfs, il est préférable de ne pas regarder directement dans GIT_DIR. Utilisez plutôt des commandes telles que git-rev-parse[1] ou git-update-ref[1] qui gèreront les réfs correctement.

FICHIER DE CONFIGURATION

Par défaut, le fichier "config" du dépôt est partagé entre tous les arbres de travail. Si les variables de configuration core.bare ou core.worktree sont déjà présentes dans le fichier de configuration, elles ne seront appliquées qu’aux arbres de travail principaux.

Afin d’avoir une configuration spécifique aux arbres de travail, vous pouvez activer l’extension "worktreeConfig", par exemple :

$ git config extensions.worktreeConfig true

Dans ce mode, la configuration spécifique reste dans le chemin indiqué par git rev-parse --git-path config.worktree. Vous pouvez ajouter ou mettre à jour la configuration dans ce fichier avec git config --worktree. Les anciennes versions de Git refuseront l’accès aux dépôts avec cette extension.

Notez que dans ce fichier, l’exception pour core.bare et core.worktree a disparu. Si vous les avez dans $GIT_DIR/config avant, vous devez les déplacer vers config.worktree de l’arbre de travail principal. Vous pouvez également profiter de cette occasion pour revoir et déplacer d’autres configurations que vous ne voulez pas partager dans tous les arbres de travail :

  • core.worktree et core.bare ne devraient jamais être partagés

  • Il est recommandé de paramétrer core.sparseCheckout par arbre de travail, à moins que vous ne soyez sûr de toujours utiliser des extractions partielles pour tous les arbres de travail.

DÉTAILS

Chaque arbre de travail lié possède un sous-répertoire privé dans le répertoire $ GIT_DIR/worktrees du dépôt. Le nom du sous-répertoire privé est généralement le nom de base du chemin de l’arbre de travail lié, éventuellement accompagné d’un numéro pour le rendre unique. Par exemple, lorsque $GIT_DIR=/chemin/principal/ .git, la commande`git worktree add /chemin/autre/test-prochain prochain` crée l’arbre de travail lié dans /chemin/autre/test-prochain et crée aussi un répertoire $GIT_DIR/worktrees/test-prochain (ou`$GIT_DIR/worktrees/test-prochain1` si test-prochain est déjà pris).

Dans un arbre de travail lié, $GIT_DIR est défini pour pointer vers ce répertoire privé (par exemple, /chemin/principal/.git/worktrees/test-prochain dans l’exemple) et $GIT_COMMON_DIR est défini pour pointer vers l’arbre de travail principal. $GIT_DIR (par exemple /chemin/principal/.git). Ces paramètres sont définis dans un fichier .git situé dans le répertoire supérieur de l’arbre de travail lié.

La résolution du chemin via git rev-parse --git-path utilise soit $GIT_DIR soit $GIT_COMMON_DIR selon le chemin. Par exemple, dans l’arbre de travail lié git rev-parse --git-path HEAD renvoie /chemin/principal/.git/worktrees/test-prochain/HEAD (pas /chemin/autre/test-prochain/.git/HEAD ou /chemin/principal/.git/HEAD) tandis que git rev-parse --git-path refs/heads/master utilise $GIT_COMMON_DIR et retourne /chemin/principal/.git/refs/heads/master, puisque les réfs sont partagées sur tous les arbres de travail, sauf refs/bisect et refs/worktree.

Voir gitrepository-layout[5] pour plus d’informations. La règle de base est de ne pas faire d’hypothèse sur l’appartenance d’un chemin à $GIT_DIR ou $GIT_COMMON_DIR lorsque vous devez accéder directement à quelque chose à l’intérieur de $GIT_DIR. Utilisez git rev-parse --git-path pour obtenir le chemin final.

Si vous déplacez manuellement un arbre de travail lié, vous devez mettre à jour le fichier gitdir dans le répertoire de l’entrée. Par exemple, si un arbre de travail lié est déplacé vers /nouveau-chemin/test-prochain et que son fichier` .git` pointe vers /chemin/principal/.git /worktrees/test-prochain, puis mettez à jour`/chemin/principal/.git/worktrees/test-prochain/gitdir` pour référencer /nouveau-chemin/test-prochain à la place.

Pour éviter qu’une entrée $GIT_DIR/worktrees ne soit élaguée (ce qui peut être utile dans certaines situations, comme lorsque l’arbre de travail de l’entrée est stocké sur un support amovible), utilisez la commande git worktree lock, qui ajoute un fichier nommé locked au répertoire de l’entrée. Le fichier contient le motif en texte clair. Par exemple, si le fichier .git d’un arbre de travail lié pointe vers /chemin/principal/.git/worktrees/test-prochain, alors un fichier nommé /chemin/principal/.git/worktrees/test-prochain/locked empêchera l’élagage de l’entrée test-prochain. Voir gitrepository-layout[5] pour plus de détails.

Lorsque extensions.worktreeConfig est activé, le fichier de configuration .git/worktrees/<id>/config.worktree est lu après .git/config.

FORMAT DE SORTIE DE LA LISTE

La commande de liste d’arbres de travail a deux formats de sortie. Le format par défaut affiche les détails sur une seule ligne avec des colonnes. Par exemple :

$ git worktree list
/chemin/vers/source-nu            (bare)
/chemin/vers/arbre-de-travail-lié        abcd1234 [master]
/chemin/vers/autre-arbre-de-travail-lié  1234abc  (detached HEAD)

Format de la porcelaine

Le format de porcelaine comporte une ligne par attribut. Les attributs sont énumérés avec une étiquette et une valeur séparées par un seul espace. Les attributs booléens (comme bare et detached) sont énumérés sous forme d’étiquette uniquement, et ne sont présents que si et seulement si la valeur est vraie. Le premier attribut d’un arbre de travail est toujours worktree, une ligne vide indique la fin de l’enregistrement. Par exemple :

$ git worktree list --porcelain
worktree /chemin/vers/source-nu
bare

worktree /chemin/vers/arbre-de-travail-lié
HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
branch refs/heads/master

worktree /chemin/vers/autre-arbre-de-travail-lié
HEAD 1234abc1234abc1234abc1234abc1234abc1234a
detached

EXEMPLES

Vous êtes au milieu d’une séance de refactorisation et votre patron arrive et exige que vous répariez quelque chose immédiatement. Vous pouvez généralement utiliser git-stash[1] pour stocker temporairement vos modifications, cependant, votre arbre de travail est dans un tel état de désordre (avec des fichiers nouveaux, déplacés et supprimés, et d’autres éléments éparpillés) que vous ne voulez pas risquer d’en déranger quoi que ce soit. Au lieu de cela, vous créez une arborescence de travail liée temporaire pour effectuer le correctif d’urgence, le supprimez lorsque vous avez terminé, puis reprenez votre session de refactoring précédente.

$ git worktree add -b correctif-d-urgence ../temp master
$ pushd ../temp
# ... travail travail travail ...
$ git commit -a -m 'correction en urgence pour le patron'
$ popd
$ git worktree remove ../temp

BOGUES

L’extraction multiple en général est encore expérimentale, et le support des sous-modules est incomplet. Il n’est PAS recommandé d’effectuer des extractions multiples d’un superprojet.

GIT

Fait partie de la suite git[1]

TRADUCTION

Cette page de manuel a été traduite par Jean-Noël Avila <jn.avila AT free DOT fr> et les membres du projet git-manpages-l10n. Veuillez signaler toute erreur de traduction par un rapport de bogue sur le site https://github.com/jnavila/git-manpages-l10n .

scroll-to-top