Jujutsu git : guide complet pour maîtriser jj pas à pas

Ce tutoriel complet vous présente Jujutsu git (souvent appelé jj), un système de contrôle de versions moderne, pensé pour simplifier le travail quotidien tout en restant compatible avec l’écosystème Git.

Qu’est-ce que Jujutsu git, à quoi il sert et qui l’utilise. Comment l’installer, ses commandes de base, un cas pratique complet pour mieux comprendre son utilisation, puis les avantages et limites, et, pour finir une conclusion et des ressources.

Jujutsu git est un outil documenté et maintenu publiquement. Sa page officielle et sa documentation permettent d’accéder aux commandes et aux guides détaillés.

• À quoi sert Jujutsu git ?
  • Objectifs principaux
  • Pour qui et pour faire quoi ?
• Les avantages de Jujutsu Git
  • Limites et précautions
• Comparatif : Git vs Jujutsu git
  • Exemple visuel d’historique Git vs Jujutsu
    • Historique avec Git classique
    • Historique avec Jujutsu git (jj)
    • Différence clé en un coup d’œil
• Comment installer Jujutsu Git
  • Installation sur macOS (méthode recommandée)
  • Installation sur Linux (méthode générale via binaire)
  • Installation sur Windows (Winget / Scoop / binaire)
  • Mise à jour et vérification
• Commandes de base et workflow
  • Concepts utiles avant de commencer
  • Initialiser un dépôt Jujutsu pour un nouveau projet
  • Exemple : récupérer le travail d’un tiers et gérer un conflit
• Commandes principales de Jujutsu Git
  • Les principaux termes de Jujutsu git :
• Exemple d’utilisation : publier une page statique sur GitHub en utilisant jj
• Atelier pratique avec Jujutsu git
  • Étape 1 : Créer un nouveau dépôt
  • Étape 2 : Ajouter un fichier et enregistrer une change
  • Étape 3 : Consulter l’historique
  • Étape 4 : Modifier un fichier et itérer
  • Étape 5 : Créer un bookmark
  • Étape 6 : Réécrire une change
  • Étape 7 : Pousser sur un dépôt GitHub
  • Étape 8 : Simuler un conflit et le résoudre

À quoi sert Jujutsu git ?

Jujutsu (commande jj) est un système de gestion de versions distribué, moderne, conçu autour d’un modèle de travail centré sur les « changes » (ensembles de modifications) plutôt que sur certains détails historiques de Git.

Il se présente comme une alternative ou un complément à Git : il peut fonctionner en mode autonome ou utiliser un dépôt Git en tant que backend pour rester compatible avec les outils et services existants.

Pour ceux qui ne savent pas comment il fonctionne, consultez notre Tutoriel complet pour utiliser Git.

Objectifs principaux

Le but principal de Jujutsu git est de rendre certaines opérations courantes plus naturelles et moins sujettes aux erreurs.

Exemples d’objectifs concrets : rendre la résolution de conflits moins pénible, éviter les manipulations implicites de pointeurs (branches), faciliter la réécriture locale et permettre des workflows où chaque état du travail est déjà enregistré sous forme de commit.

Pour qui et pour faire quoi ?

Vous pouvez utiliser Jujutsu si vous voulez :

1. Expérimenter un flux de travail différent sans perdre la compatibilité avec Git.
2. Gérer des branches empilées et des réécritures locales de façon plus simple.
3. Profiter d’un système qui enregistre automatiquement l’état du répertoire de travail (plus de stash ou d’index à gérer manuellement).

Le mode co-located (jj git init --colocate) permet de l’adopter progressivement sur des projets Git existants, ce qui est pratique pour tester sans s’imposer trop de changements.

Les avantages de Jujutsu Git

Gestion des conflits « first-class »
Jujutsu peut enregistrer les états conflictuels dans l’historique. Concrètement, si un rebase produit un conflit, l’opération peut se terminer et le conflit reste enregistré. Ainsi vous pouvez revenir plus tard le résoudre, réécrire l’historique qui en dépend, ou propager la résolution automatiquement. Cela évite de perdre du temps à résoudre les mêmes conflits plusieurs fois.

Modèle de pointeurs plus explicite (bookmarks)
Dans jj, les noms attachés à des révisions s’appellent des bookmarks. Contrairement aux branches Git, ces bookmarks ne bougent pas automatiquement à chaque commit. Cette stabilité force une action explicite pour déplacer un pointeur et limite les effets de surprises quand on réécrit l’historique. 

Workflow « tout est commit »
Le répertoire de travail est représenté par un commit réel. Les changements non finalisés existent déjà comme commits internes, ce qui évite l’usage intensif d’un index ou d’un stash. Cette approche rend certaines opérations (squash, split, réécriture) très naturelles.

Compatibilité Git native
Il est possible d’utiliser jj avec des dépôts Git existants sans casser le workflow existant. jj peut coexister avec Git et interagir avec les remotes GitHub/GitLab via des commandes intégrées.

Limites et précautions

Adhésion et outils tiers
L’écosystème autour de Git (CI, IDE, hooks, certaines intégrations) est très mature. L’adoption complète de Jujutsu peut nécessiter des adaptations et des tests pour vérifier que tous les outils fonctionnent comme attendu.

Jeune projet et changements fréquents
Jujutsu progresse rapidement ; certaines commandes et comportements évoluent. Il faut donc s’attendre, occasionnellement, à des notes de version et à des mises à jour qui changent légèrement le fonctionnement. La consultation régulière de la documentation officielle est recommandée.

Mental model différent
La philosophie de travail (changes, bookmarks, op-log, conflicts enregistrés) diffère de Git. Il faut un temps d’apprentissage, surtout si l’on est habitué aux commandes et aux habitudes Git. Plusieurs ressources et tutoriels existent pour faciliter la transition.

Comparatif : Git vs Jujutsu git

Ce tableau met en lumière la complémentarité entre Git et Jujutsu : Git reste incontournable dans l’écosystème, mais Jujutsu propose un modèle plus intuitif et moderne, qui simplifie des tâches souvent compliquées avec Git.

Exemple visuel d’historique Git vs Jujutsu

• Vous avez une branche main.
• Vous créez une branche feature.
• Vous modifiez un fichier dans main et dans feature sur la même ligne → un conflit est inévitable.
• Vous tentez de rebaser feature sur main.

Historique avec Git classique

Avant le rebase :

main:  A --- B
             \
feature:       C --- D

• A = commit initial
• B = modification sur main
• C, D = commits sur feature

Après git rebase main sur feature, Git s’arrête sur un conflit :

main:  A --- B
             \
feature:       C' (conflit bloqué)

• C' est une tentative de rebase de C sur B, mais l’opération est bloquée.
• Tant que vous n’avez pas résolu le conflit et validé avec git add + git rebase --continue, vous ne pouvez pas avancer.

Si vous quittez ou échouez, il faut souvent faire git rebase --abort, et vos changements risquent d’être perdus ou en désordre.

Historique avec Jujutsu git (jj)

Avant le rebase (même situation) :

◉  A
│
◉  B  (main)
│
│ ◉  C
│ │
│ ◉  D  (feature)

Après jj rebase --source feature --destination main :

◉  A
│
◉  B  (main)
│
│ ◉  C' (conflit enregistré)
│ │
│ ◉  D'
│
@  (working-copy)

Explications :

• C' est une version de C rebasée sur B.
• Le conflit est enregistré dans l’historique (il fait partie d’un commit).
• Vous pouvez continuer à travailler : créer d’autres commits, explorer, même changer de branche.
• Plus tard, vous résolvez le conflit avec :

jj resolve
jj resolve --done

Et jj met à jour l’historique sans perdre les changements effectués dans l’intervalle.

Différence clé en un coup d’œil

• Git classique : conflit = opération bloquée. Vous êtes obligé de résoudre avant d’avancer.
• Jujutsu git : conflit = état enregistré. Vous pouvez avancer, et résoudre quand vous voulez, sans perdre d’historique.

Comment installer Jujutsu Git

Avant d’installer, vérifiez la documentation officielle et les pages de release pour choisir la version adaptée à votre système. Les méthodes ci-dessous couvrent les installations usuelles : Homebrew (macOS / Linux), installation via les binaires précompilés (Linux/macOS/Windows) et gestionnaires de paquets Windows.

Installation sur macOS (méthode recommandée)

Commencez par ouvrir le Terminal. Si Homebrew n’est pas installé, installez-le via la page officielle Homebrew. Enfin, tapez la commande suivante :

brew install jj

Explication : Homebrew distribue une formule jj officielle ; l’installation est rapide et facilite les mises à jour futures (brew upgrade jj). La page Homebrew référence la formule dédiée à jj.

Installation sur Linux (méthode générale via binaire)

Rendez-vous sur la page des releases du dépôt GitHub de jj. Téléchargez l’archive correspondant à votre architecture (par exemple jj-<version>-x86_64-unknown-linux-gnu.tar.gz). Enfin, décompressez l’archive et placez le binaire dans un répertoire accessible par votre PATH, par exemple /usr/local/bin ou ~/bin :

tar -xzf jj-<version>-x86_64-unknown-linux-gnu.tar.gz
sudo mv jj /usr/local/bin/

Étape 4 : Vérifiez l’installation :

jj --version

Les releases contiennent des binaires musl et glibc ; choisissez celui qui correspond à votre distribution. L’approche par binaire évite d’installer tout l’environnement de compilation. 

Installation sur Windows (Winget / Scoop / binaire)

Si vous utilisez Winget (Windows 10/11), exécutez dans PowerShell :

winget install --id Jujutsu.Jujutsu

Étape 2 : Avec Scoop, installez Scoop puis :

scoop install jj

Étape 3 : Vérifiez :

jj --version

Plusieurs gestionnaires (Winget, Scoop) proposent jj. Si vous préférez, téléchargez le binaire depuis la page de release et placez-le dans un dossier inclus dans le PATH.

Mise à jour et vérification

Vérifiez la version installée :

# macOS
brew upgrade jj

Pour mettre à jour, utilisez la méthode de distribution choisie (Homebrew : brew upgrade jj, Winget : winget upgrade, etc.). Suivre les notes de version est utile car jj évolue et introduit parfois de nouvelles commandes ou modifie des comportements.

Commandes de base et workflow

Nous allons maintenant apprendre à utiliser jj au quotidien. Les explications sont données ligne par ligne, avec le sens de chaque commande. Les exemples partent d’un projet neuf et d’un dépôt Git existant.

Concepts utiles avant de commencer

Le terme change dans jj correspond à l’unité de travail principal (semblable à un commit, mais mutable). Le working-copy commit est une représentation réelle du répertoire de travail, et bookmarks servent de pointeurs nommés vers des revisions. Le journal des opérations (jj op) enregistre les actions locales. Ces notions changent légèrement la façon de penser par rapport à Git. 

Initialiser un dépôt Jujutsu pour un nouveau projet

Étape 1 : Créez un nouveau dossier et déplacez-vous dedans.

mkdir site-demo
cd site-demo

Étape 2 : Initialisez un dépôt Jujutsu simple (qui utilise Git comme backend et crée un dépôt Git local) :

jj git init

Donc, quand vous tapez cette commande, vous n’initialisez pas un dépôt Git, mais un dépôt Jujutsu qui peut être relié à Git.

Concrètement :

• git init crée un dépôt Git avec un dossier caché .git/.
• jj git init crée un dépôt Jujutsu, et en plus un lien vers Git si vous lui précisez de le faire (mais il ne crée pas automatiquement un .git/ comme le ferait git init).

C’est pourquoi, si vous exécutez ensuite :

git status

Git ne trouve pas de dépôt donc il affiche la réponse : fatal: ni ceci ni aucun de ses répertoires parents n'est un dépôt git : .git.

Si vous souhaitez un dépôt Git pur :

git init

Si vous souhaitez un dépôt Jujutsu relié à Git (hybride) :

jj init --git

ou bien, si votre dépôt Git existe déjà :

jj git init

Dans ce dernier cas, vous devez d’abord avoir fait git init pour que le dossier .git/ existe. Donc, dans notre situation :

• Si vous vouliez un dépôt Git → utilisez git init.
• Si vous vouliez Jujutsu avec support Git → faites git init puis jj git init.

 jj git init initialise un dépôt jj et crée en option le dépôt Git nécessaire si vous voulez rester compatible avec l’écosystème Git. Cela permet d’utiliser plus tard git ou jj git pour pousser sur des remotes.

Étape 3 : Créez un fichier index.html :

cat > index.html <<'HTML'
<!doctype html>
<html>
  <head><meta charset="utf-8"><title>Site demo</title></head>
  <body><h1>Bonjour Jujutsu</h1></body>
</html>
HTML

Étape 4 : Sauvegardez l’état en “commitant” avec jj :

Configurez vos informations d’utilisateur dans Jujutsu avec :

jj config set --user user.name "Votre Nom"
jj config set --user user.email "[email protected]"

Où ces paramètres sont enregistrés ? Ils sont stockés dans la configuration de Jujutsu (similaire au .gitconfig de Git). Vous pouvez vérifier avec :jj config list --user.

Une fois renseigné, vos prochains commits auront une identité complète et pourront être synchronisés avec un dépôt Git distant.

Des formations informatique pour tous !

Débutant ou curieux ? Apprenez le développement web, le référencement, le webmarketing, la bureautique, à maîtriser vos appareils Apple et bien plus encore…

Formateur indépendant, professionnel du web depuis 2006, je vous accompagne pas à pas et en cours particulier, que vous soyez débutant ou que vous souhaitiez progresser. En visio, à votre rythme, et toujours avec pédagogie.

Découvrez mes formations Qui suis-je ?

jj commit -m "feat: add index.html"

jj commit est un raccourci qui décrit la change courante puis crée une nouvelle change (c’est l’équivalent pratique de jj describe suivi de jj new). Le message expliqué ici sert d’annotation pour la change. jj enregistre automatiquement l’état du working-copy commit ; il n’y a pas d’étape git add séparée comme dans Git classique.

Étape 5 : Créez un bookmark pour nommer cette change (utile pour la partager) :

jj bookmark create feature/landing -r @-

@- réfère au parent du working-copy commit. La commande crée un nom (bookmark) qui pointe sur le commit que vous venez d’enregistrer. Contrairement aux branches Git, les bookmarks ne se déplacent pas automatiquement.

Étape 6 : Ajoutez un remote Git (si vous voulez pousser sur GitHub) :

git remote add origin https://github.com/votre-username/site-demo.git

Étape 7 : Poussez la change/bookmark vers le dépôt distant :

jj git push --allow-new origin feature/landing

La sous-commande jj git push utilise l’infrastructure Git pour communiquer avec le remote. L’option --allow-new autorise la création d’une nouvelle branche distante correspondant au bookmark local. 

Exemple : récupérer le travail d’un tiers et gérer un conflit

Scénario : un collègue a modifié index.html sur la branche distante.

Étape 1 : Récupérez les mises à jour distantes :

jj git fetch

Étape 2 : Consultez les bookmarks distants :

jj bookmark list --remote

Étape 3 : Pour appliquer une change distante sur votre travail, utilisez jj rebase ou jj merge. Par exemple :

jj rebase --source <id-de-la-change-distante> --destination @-

Si la rebase provoque des conflits, jj va enregistrer la state conflictuelle comme un commit. Vous pourrez alors utiliser jj resolve pour ouvrir votre outil de fusion et résoudre les fichiers concernés. Une fois résolu, jj resolve signale la résolution et l’historique est cohérent. Vous pouvez reprendre d’autres opérations ensuite.

Étape 4 : Ouvrir l’outil de résolution intégré ou externe :

jj resolve

jj resolve invoque l’outil de merge configuré pour résoudre les conflits fichier par fichier. Après cela, la change conflictuelle peut être marquée comme résolue et la rebase/merge se poursuit sans perdre le travail effectué. 

Commandes principales de Jujutsu Git

Voici un mémo clair des commandes les plus utiles de Jujutsu git :

Les principaux termes de Jujutsu git :

• Commit : état immuable du projet.
• Change-id : identifiant logique regroupant plusieurs révisions d’un même commit.
• Change : ensemble de commits liés par un change-id.
• Operation : action enregistrée dans le journal des opérations (commit, amend, rebase…).
• Working Copy (@) : copie de travail courante des fichiers.
• Branch : nom pointant vers un ou plusieurs commits.
• Bookmark : pointeur explicite vers un commit, similaire à une étiquette ou une branche Git fixe.
• Revset : langage de requêtes pour cibler des commits.
• Rebase automatique : ajustement implicite des commits pour garder un historique clair.
• Description : message attaché à un commit (titre + détails).
• Head : commit sans enfant.
• Obslog : historique des révisions d’un commit.

Exemple d’utilisation : publier une page statique sur GitHub en utilisant jj

Notre objectif est de publier une page statique sur GitHub en utilisant jj, faire une itération locale, recevoir une modification distante et résoudre un conflit en conservant l’historique propre.

Étape A : Initialisation et premier commit. Nous allons créer le projet et l’initialiser :

mkdir demo-jujutsu && cd demo-jujutsu
jj git init

Créez index.html et faites :

jj commit -m "chore: initial site"
jj bookmark create main -r @-

Ajoutez le remote GitHub et poussez :

git remote add origin https://github.com/votre-username/demo-jujutsu.git
jj git push --allow-new origin main

Étape B : Travail local (nouvelle fonctionnalité). Nous allons modifier index.html pour ajouter une section “À propos”. Pour enregistrer l’itération :

jj commit -m "feat: add about section"
jj bookmark create feat/about -r @-
jj git push --allow-new origin feat/about

Étape C : Arrivée d’une modification distante (scénario conflit). Un collaborateur a modifié la même section et poussé sur main. On commence par récupérer :

jj git fetch

Puis, réintégrez main dans votre branche :

jj rebase --source main --destination @-

Si la rebase produit un conflit, jj enregistrera une change conflictuelle. La console affichera les fichiers concernés.

Étape D : Résolution et continuation. Lancez l’outil de résolution :

jj resolve

Après la résolution fichier par fichier, marquez comme résolu (si l’outil ne le fait pas automatiquement) et terminez :

jj resolve --done

Enfin, poussez la change résultante vers le remote :

jj git push --allow-new origin feat/about

Ce workflow illustre la robustesse de jj face aux conflits : l’opération de rebase ne vous empêche pas d’avancer, l’état conflictuelle est enregistré, et la résolution se fait sans perdre l’alignement des changes.

Atelier pratique avec Jujutsu git

Pour terminer notre tutoriel, on se répète, mais cela aide à mieux comprendre. Voici donc atelier complet qui a pour objectif de vous faire manipuler jj de manière progressive, comme si vous découvriez Git pour la première fois. On reprends son utilisation de A à Z avec l’ensemble de ses fonctionnalités.

Vous pouvez suivre chaque commande et observer le résultat dans votre terminal. L’exemple fonctionne sur Linux, macOS et Windows (PowerShell ou Git Bash).

Étape 1 : Créer un nouveau dépôt

Dans un dossier de travail, tapez :

mkdir atelier-jj
cd atelier-jj
jj git init

Vous venez de créer un nouveau dossier et d’initialiser un dépôt jj avec Git comme backend. Cela veut dire que vous pouvez utiliser à la fois jj et git dans ce dossier.

Étape 2 : Ajouter un fichier et enregistrer une change

Créez un fichier :

echo "<h1>Bonjour Jujutsu</h1>" > index.html

Puis enregistrez-le :

jj commit -m "feat: ajouter un fichier index.html"

Pas besoin de git add, jj prend en compte directement les fichiers du répertoire de travail et crée une change (équivalent d’un commit).

Étape 3 : Consulter l’historique

Tapez :

jj log

Vous verrez une représentation graphique de vos changes.
Exemple simplifié :

@  d4f6e9b6 feat: ajouter un fichier index.html
│
◉  00000000 (root)

Le symbole @ indique votre working-copy (l’état courant).

Étape 4 : Modifier un fichier et itérer

Éditez index.html pour ajouter un paragraphe, puis tapez :

jj commit -m "Modif: ajouter un paragraphe de bienvenue"

Chaque enregistrement crée une nouvelle change au-dessus de la précédente. Vous construisez votre historique pas à pas.

Étape 5 : Créer un bookmark

Pour donner un nom à votre état actuel :

jj bookmark create main -r @-

Vous avez maintenant un bookmark main qui pointe sur la dernière change. Contrairement à une branche Git, ce bookmark ne bougera pas tout seul : vous devrez explicitement le déplacer.

Étape 6 : Réécrire une change

Vous avez remarqué une faute dans votre dernier message de commit ? Pas de problème :

jj describe -m "Modif: ajouter un paragraphe d'accueil"

La commande jj describe modifie le message de la change courante. Vous pouvez également modifier le contenu du commit si vous changez des fichiers avant de lancer la commande.

Étape 7 : Pousser sur un dépôt GitHub

Ajoutez un remote :

git remote add origin https://github.com/votre-username/atelier-jj.git

Puis poussez :

jj git push --allow-new origin main

Même si vous utilisez jj, vos collègues qui travaillent avec git classique verront vos commits sur GitHub. C’est la grande force de Jujutsu.

Étape 8 : Simuler un conflit et le résoudre

Modifiez index.html localement. Pendant ce temps, imaginez qu’un collègue a poussé une autre version sur GitHub. Récupérez-la :

jj git fetch

Puis tentez de rebaser :

jj rebase --source main --destination @-

Si un conflit apparaît, tapez :

jj resolve

Vous ouvrez alors votre outil de fusion habituel pour régler le conflit. Une fois résolu :

jj resolve --done

Le conflit est enregistré comme un état de l’historique, vous n’êtes jamais bloqué.

Ce guide vous a proposé un panorama complet de Jujutsu git : définition, objectifs, avantages, limites, installation, commandes de base, et cas pratique détaillé. 

jj offre une approche moderne et convaincante pour certaines tâches qui sont historiquement pénibles en Git, notamment la résolution de conflits et la gestion des commits locaux.

Jujutsu conserve la compatibilité avec Git, ce qui facilite son adoption progressive dans des projets existants. Pour commencer, il est conseillé d’installer jj sur un projet personnel ou un dépôt de test, d’expérimenter le modèle de changes / bookmarks, puis d’envisager une adoption plus large. Allez-y étape par étape, progressivement.

1. Avant de l’adopter en production sur un projet d’équipe, testez jj sur un dépôt cloné pour maîtriser l’impact des bookmarks et du workflow.
2. Lisez les notes de version avant chaque mise à jour majeure, car jj évolue régulièrement. 
3. Utilisez le mode co-located (jj git init --colocate) pour expérimenter jj sans couper la compatibilité Git.

Alban

Fondateur de l’agence Créa-troyes.
Intervenant en Freelance.
Contactez-moi

crea-troyes.fr