Setup and Config
Getting and Creating Projects
Basic Snapshotting
Branching and Merging
Sharing and Updating Projects
Inspection and Comparison
Patching
Debugging
External Systems
Server Admin
Guides
- gitattributes
- Command-line interface conventions
- Everyday Git
- Frequently Asked Questions (FAQ)
- Glossary
- Hooks
- gitignore
- gitmodules
- Revisions
- Submodules
- Tutorial
- Workflows
- All guides...
Administration
Plumbing Commands
- 2.43.0 no changes
-
2.42.1
11/02/23
-
2.42.0
08/21/23
- 2.39.1 → 2.41.0 no changes
-
2.39.0
12/12/22
- 2.36.1 → 2.38.5 no changes
-
2.36.0
04/18/22
- 2.35.1 → 2.35.8 no changes
-
2.35.0
01/24/22
- 2.33.1 → 2.34.8 no changes
-
2.33.0
08/16/21
- 2.31.1 → 2.32.7 no changes
-
2.31.0
03/15/21
- 2.30.1 → 2.30.9 no changes
-
2.30.0
12/27/20
- 2.29.1 → 2.29.3 no changes
-
2.29.0
10/19/20
- 2.28.1 no changes
-
2.28.0
07/27/20
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 variablecheckout.defaultRemote=originpar exemple pour extraire toujours les branches distantes depuis celle-ci si <branche> est ambigüe mais existe sur le distant origin. Voir aussicheckout.defaultRemotedans git-config[1].Si
<commit-esque>est omis et que ni-bni-Bni--detachne 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--forcesoit 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,
addrefuse 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--forcedeux fois.moverefuse de déplacer un arbre de travail verrouillé à moins que--forcene 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--forcepermet au déplacement de continuer ; utilisez --force deux fois si la destination est verrouillée.removerefuse de supprimer un arbre de travail sale à moins que--forcene 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,-brefuse de créer une nouvelle branche si elle existe déjà.-Bannule 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-checkoutpeut ê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 lockaprèsgit 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.worktreeetcore.barene devraient jamais être partagés -
Il est recommandé de paramétrer
core.sparseCheckoutpar 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 .
