Jujutsu pour tout le monde

• Ce document est un tutoriel pour débutants qui enseigne Jujutsu (VCS) étape par étape, avec une progression organisée par niveaux, afin d’être accessible même sans expérience de Git
• Il part du principe que l’on utilise le terminal, mais couvre aussi les bases du terminal ; les principales commandes sont expliquées surtout pour Linux/macOS, et WSL est recommandé aux utilisateurs de Windows
• Le parcours d’apprentissage consolide les bases, la collaboration et la résolution de problèmes aux niveaux 1 à 3, puis s’étend aux réécritures d’historique et workflows avancés dans les niveaux supérieurs
• Pour les cas où l’état du tutoriel se retrouve désynchronisé en cours de route, un environnement d’apprentissage reproductible est fourni grâce à un script de reset permettant de revenir au point de départ de chaque chapitre
• Pour expliquer pourquoi choisir Jujutsu plutôt que Git, le document met en avant sa compatibilité avec Git, sa courbe d’apprentissage plus douce et ses fonctionnalités avancées ; le contenu est en cours de mise à jour sur la base de Jujutsu 0.32

---

Introduction

• Ce tutoriel est une ressource d’initiation destinée aux personnes qui utilisent Jujutsu pour la première fois
• Il propose un contenu centré sur les débutants pour compenser la limite des ressources Jujutsu existantes, souvent axées sur la transition d’utilisateurs Git expérimentés
• L’usage du terminal est la base, et le tutoriel inclut un chapitre sur les fondamentaux du terminal ; pour les utilisateurs de Windows, l’usage de WSL est recommandé

Comment lire ce tutoriel

• Le contenu est organisé par niveaux, avec une progression pensée pour pratiquer réellement après chaque niveau avant de passer au suivant
• Si votre objectif est la collaboration, il est recommandé de suivre les niveaux 1 et 2 à la suite
• Aperçu des niveaux
  • Niveau 1 : fournit le minimum pour démarrer en travail individuel ; adapté par exemple à un étudiant gérant seul ses devoirs
  • Niveau 2 : le minimum nécessaire pour collaborer, utile pour les projets d’équipe étudiants comme pour les développeurs en activité
  • Niveau 3 : bases de la résolution de problèmes, comme les conflits et la récupération ; correspond au niveau moyen attendu d’un développeur
  • Niveau 4 : réécriture de l’historique pour construire un historique propre ; nécessaire pour satisfaire les exigences de qualité de certains projets
  • Niveau 5 : boosters de productivité, workflows avancés, CLI rare et théorie, soit le niveau maîtrise de Jujutsu
  • Niveau 6 : sujets contextuels comme les tags, submodules et workspaces, à consulter selon les besoins

Raccourcis clavier

• Navigation entre les chapitres avec les flèches gauche et droite
• S ou / permet la recherche dans le livre
• ? affiche l’aide, et Esc la masque

Réinitialiser votre progression

• L’état du dépôt d’exemple est lié au chapitre suivant, donc perdre cet état peut bloquer la progression
• Pour résoudre cela, un script reset.sh est fourni afin de restaurer le point de départ d’un chapitre
• Le début de chaque chapitre inclut la commande de reset exacte, ce qui permet une reproduction par simple copier-coller
• Il est recommandé de vérifier le contenu du script avant exécution ; en pratique, il s’agit d’un comportement simple, proche d’un ensemble de commandes manuelles
• Principales caractéristiques du script
  • JJ_CONFIG=/dev/null pour neutraliser l’impact de la configuration utilisateur
  • Création du dépôt d’exemple, intégration Git colocated, configuration des informations utilisateur, reconstruction de scénarios successifs incluant commit/push/fetch/rebase, etc.
  • Conception avec branchement permettant de terminer avec succès à l’endroit voulu en recevant en argument les mots-clés de chaque chapitre

Rester à jour

• Le tutoriel et Jujutsu sont en évolution continue ; en s’abonnant aux Releases du dépôt du tutoriel, il est possible de recevoir les annonces des changements majeurs
• Le tutoriel indique être à jour sur la base de Jujutsu 0.32 (août 2025)
• Il fournit aussi la marche à suivre sur GitHub pour configurer les notifications : Watch → Custom → Releases

Qu’est-ce que le contrôle de version et pourquoi l’utiliser ?

• C’est un moyen de gérer l’accumulation progressive du travail, applicable non seulement au logiciel mais aussi à la rédaction de documents comme Typst
• Il permet de revenir à un état antérieur et prend en charge en toute sécurité le travail simultané de plusieurs personnes
• Quand on a besoin d’un outil de contrôle plus fin qu’une simple sauvegarde ou qu’un éditeur collaboratif, Jujutsu est adapté

Pourquoi Jujutsu plutôt que Git ?

• Compatibilité Git : interopérabilité sans perte avec les dépôts Git existants, avec possibilité de continuer à utiliser la plupart des outils intégrés à Git
• Facilité d’apprentissage : par rapport à l’interface complexe et peu intuitive de Git, Jujutsu fournit les mêmes fonctions avec une complexité plus faible
• Fonctionnalités plus puissantes : au-delà de sa facilité d’apprentissage, il propose de nombreuses fonctions pour power users, garantissant une bonne extensibilité des workflows
• Inconvénients et points à considérer
  • Dans les échanges, il existe une charge de mise en correspondance conceptuelle avec une culture dominée par la terminologie Git ; cela peut être atténué en convainquant ses collègues
  • Comme il s’agit d’un outil relativement récent, certaines fonctions de Git peuvent manquer ; si nécessaire, on peut revenir directement à Git
  • La CLI est encore en phase de stabilisation, donc certaines commandes peuvent évoluer ; il est recommandé de suivre les releases du tutoriel pour rester informé

Progression d’apprentissage

• À l’heure actuelle, la structure est surtout centrée sur les niveaux 1 à 3 afin d’assimiler un flux de travaux pratiques couvrant l’installation → l’initialisation → logs/commits → remote/push/clone → branches/merge → rebase → navigation → annulation/récupération → résolution de conflits → nettoyage
• Les niveaux supérieurs proposent ensuite une montée en compétence progressive avec l’apprentissage supplémentaire de la réécriture, des workflows avancés et de sujets plus rares

[GN⁺]

Discussion Hacker News

• J’ai l’impression n’avoir vu que des dizaines d’articles élogieux sur jj. Ce tutoriel est un peu du même genre, mais maintenant que j’ai assez lu sur ses qualités, je m’intéresse davantage à ses défauts et à ses points gênants. En essayant jj, j’y ai trouvé des avantages comme des inconvénients. J’utilise souvent un workflow où je partage une branche avec des collègues et où l’on continue d’empiler des commits, mais avec jj, comme il n’y a pas de branches nommées, c’était plus contraignant à utiliser que git, même avec l’alias tug. La section « Tracking remote bookmarks » du tutoriel me semble aussi toujours peu pratique. Un autre point gênant était que jj ne pouvait pas utiliser de clone léger comme git clone --filter=blob:none, et je me demande si cela a été corrigé

  • jj a bien des branches nommées ; dans jj, on les appelle des « bookmarks ». Si on suit un bookmark distant, jj git fetch synchronise le local avec le distant

  • Une des choses qui m’a posé problème, c’est que jj semblait parfois perdre mes modifications de façon aléatoire. Je travaillais dans Cursor sans modifier le dépôt avec jj — je faisais juste des jj status, jj log, ce genre de choses — puis plus tard je constatais que mes changements avaient disparu, avec parfois un message « stale workspace ». Je ne sais pas si c’est lié à l’IDE ou à un énorme monorepo, mais c’était vraiment pénible. Cela dit, j’apprécie beaucoup la flexibilité de jj

  • Il y a une discussion sur https://github.com/jj-vcs/jj/discussions/3549 pour simplifier un peu plus le workflow tug

  • Dire que jj n’a pas de branches nommées est incorrect. Il faut certes les définir manuellement avec quelque chose comme jj branch set -r@ XYZ, ce qui est un peu fastidieux, mais il suffit de le faire une fois au moment du push. Sinon, on peut aussi déplacer la branche avec jj git push --named XYZ=@

  • Le fait que jj ne prenne pas en charge les clones légers (git clone --filter=blob:none) n’est toujours pas résolu

• On dit que « Jujutsu est plus puissant que Git », mais rien n’explique concrètement en quoi il est plus puissant, donc je me demande vraiment pourquoi je devrais l’utiliser. Cela ressemble à une simple formule creuse

  • Je suis l’auteur du tutoriel. Comme il s’adresse aux débutants, une comparaison détaillée avec Git n’aurait pas été appropriée. La complexité de l’interface de Git est souvent justifiée par sa « puissance », donc je voulais simplement ajouter cette remarque pour faire comprendre aux utilisateurs qu’avec Jujutsu, ils ne perdent pas de fonctionnalités sous prétexte qu’il est plus facile à apprendre

  • Par exemple, on crée une nouvelle branche depuis la branche main, avec l’intention d’en faire plus tard une PR. On empile plusieurs commits, puis on se rend compte qu’il faut modifier le commit n°1. Il suffit de modifier ce commit et d’enregistrer : tous les autres commits sont automatiquement rebasés sur la version à jour. Même après la PR, si l’on veut modifier le commit n°3, il suffit d’éditer ce commit et de push. Faire cela directement avec Git est vraiment difficile. Mes collègues aiment beaucoup les PR découpées en plusieurs commits

  • Je pense à peu près la même chose. Je trouve que les interfaces Git sont globalement insuffisantes, donc je serais prêt à utiliser jj avec un certain niveau de confiance. Mais j’aurais aimé voir des démonstrations plus concrètes de « pourquoi c’est plus simple, plus puissant ou plus pratique »

  • Un exemple : on peut enregistrer un conflit de fusion comme un élément unique et le traiter plus tard : https://jj-vcs.github.io/jj/latest/conflicts/

• J’ai réessayé JJ récemment, et c’est devenu bien meilleur ; je l’utilise maintenant avec plaisir. Quand je l’avais essayé au début, il y avait beaucoup d’angles vifs qui le rendaient rebutant, mais je pense que JJ fait partie d’une nouvelle vague remarquable d’outillage apparue récemment. J’en ai aussi parlé sur mon blog : https://pdx.su/blog/2025-08-13-the-quiet-software-tooling-renaissance/

  • Très bon article. Je pense vraiment que le niveau de l’outillage de développement a énormément monté ces dernières années. Rust fait aussi partie de cette évolution

  • Ravi de voir que vous utilisez et appréciez aussi mise. mise, jj (ainsi que le très cool TUI jjui), et uv pour Python sont tous révolutionnaires. Je trouve ces outils vraiment magnifiques

  • J’aimerais absolument ajouter nushell à cette liste

  • Bun est aussi à l’avant-garde de cette révolution de l’outillage

• Excellent travail ! Cela fait presque 5 mois que j’utilise uniquement Jujutsu et qu’il a complètement remplacé git. En pratique, pendant cette période, je n’ai lancé Git que 52 fois (dont 11 avec --help), alors que j’ai utilisé Jujutsu 582 fois. Sans avoir à se plier à un workflow précis, Jujutsu est suffisamment flexible pour prendre en charge presque tous les workflows. Même en l’utilisant comme git, on peut déplacer librement commits et branches sans avoir besoin de stash, rebaser facilement — ce qui est peut-être naturel pour les experts git, mais je suis vraiment reconnaissant de pouvoir le faire directement sans l’outil git de VSCode — et se concentrer sur le travail sans les aspects pénibles typiques d’un VCS. À noter que l’historique reste aussi présent dans le dépôt git sous-jacent, donc tout cela reste compatible avec les autres outils git. Autrement dit, je peux utiliser autre chose sans que mes collègues aient à changer de VCS. Il y a quelques manques du côté des tags, des submodules et de LFS, mais cela vaut largement le coup d’essayer

  • Je me demande quelle est l’alternative jj à git branch --set-upstream-to

  • Une fois qu’on a essayé jjui, on touche quasiment plus jamais aux commandes jj. C’est vraiment impressionnant

• Jujutsu est vraiment pas mal. Je l’ai essayé il y a quelques mois et j’ai écrit quelques billets à ce sujet (celui-ci), et depuis je continue à l’utiliser. Globalement, l’expérience est très « cohérente ». En réalité, j’étais déjà quelqu’un qui utilisait git sans problème, mais avec jj tout repose sur quelques principes de base, et on peut les combiner comme on veut pour modifier facilement des historiques complexes. Je travaillais surtout à base de stash, et jj est bien plus agréable que git grâce au suivi automatique des changements, au déplacement libre des modifications, etc. Le rebase et la résolution des conflits sont aussi bien meilleurs, surtout dans un workflow de type stash. Je le recommande vivement, et l’effort nécessaire pour y passer est très faible

• Personnellement, je n’aime pas beaucoup l’approche qui consiste à ajouter une nouvelle couche au-dessus de git. Je comprends qu’il soit difficile de briser l’hégémonie de git, mais je pense qu’il serait bien plus puissant et plus libre de construire sur des fondations entièrement nouvelles

• J’ai utilisé jj pendant environ un mois, puis je suis revenu à git à cause d’un projet spécifique au travail. J’aimais vraiment jj, mais pas plus que ça. Pourtant, quelques heures après être revenu à git, la commodité de jj me manquait énormément : https://blog.nawaz.org/posts/2025/Aug/the-jujutsu-effect/

  • Je me demande ce que signifie exactement « mais pas plus que ça »

  • Cela veut dire qu’on ne réalise sa vraie valeur qu’une fois qu’on l’a perdue

• J’aimerais lire davantage sur le thème « Jujutsu pour experts Git ». Par exemple, je me demande si le fait de committer les conflits ne risque pas de casser mon git rerere, ou s’il existe dans jj un moyen simple d’implémenter des patchsets en deux étapes, alors qu’avec git j’aime souvent ne stage qu’une partie d’un patch avec git add -p. Je veux éviter la corruption des horodatages et les rebuilds inutiles de systèmes de build

  • Je réponds avec le workflow le plus courant dans jj (« squash workflow »). On modifie librement dans le top commit, qui est le répertoire de travail, puis quand on veut « stage », on squash vers le commit inférieur — donc un niveau en dessous — soit en entier, soit partiellement avec -i. On peut aussi utiliser squash --into pour cibler un autre commit et faire le squash exactement où l’on veut

  • 1. jj n’utilise pas git rerere, donc la question est un peu à côté. 2. @ est l’espace de travail, et @- est le commit sur lequel on travaille. Avec jj squash -i, on peut renvoyer interactivement vers @ seulement la partie du diff que l’on souhaite

  • Même si je suis d’accord avec l’idée que « la distinction stage/unstage est inutile », je trouve étonnant de dire en même temps que « ne stage que les morceaux du patch qu’on aime, c’est vraiment génial ». On peut obtenir un effet similaire sans staging en combinant git worktree, git diff, vi et git apply, mais c’est vraiment pénible. Même dans mercurial 7.1, il n’y a toujours pas d’ajout interactif, donc à part des contournements via worktree, il n’y a pas vraiment d’alternative

• Je vois passer des discussions sur Jujutsu depuis peu, mais sans entrer dans les workflows concrets. Je me demande si Jujutsu a un avantage particulier par rapport à Emacs Magit. Jusqu’ici, la plupart des interfaces Git que j’ai essayées m’ont semblé insuffisantes, mais Magit a énormément amélioré ma productivité avec git et m’a fait ressentir cette « magie » de git. Est-ce que Jujutsu cherche à rivaliser avec cette expérience, ou vise-t-il plutôt à proposer une alternative aux interfaces git existantes, qui sont vraiment insuffisantes ?

  • Jujutsu n’est pas une simple interface git ; au contraire, il est plutôt faible en tant qu’interface git, notamment par manque de prise en charge des tags, submodules, etc. C’est un VCS entièrement nouveau qui utilise git comme backend. Si git a apporté les « cheap branches » face à SVN, JJ apporte les « cheap rebases ». Les conflits n’interrompent pas tout le travail, et le rebase comme la gestion de la structure des commits sont vraiment pratiques. Si vous avez déjà utilisé les stacked diffs, cela vous paraîtra familier, et des PR en stacked diff deviennent possibles dans jj avec très peu d’effort

  • Si vous utilisez déjà beaucoup Magit, les concepts de base de jj devraient aussi vous séduire. jj permet des acrobaties sur les commits qu’on pensait auparavant impossibles, comme rebaser deux feuilles d’une fusion octopus à 5 branches tout en laissant les conflits non résolus. C’est une technique que j’ai mise au point sous le nom de « Mega Merge ». Il y a une parenté entre Magit et jj : la « magie de git » vient en réalité du « langage de design » de l’outil. Git n’est que la couche de stockage physique pour Magit comme pour jj, mais les différences sont énormes en matière d’algorithmes, d’UX et de concepts. Les utilisateurs de Magit sont généralement moins déstabilisés par jj, mais les utilisateurs avancés de Git en ligne de commande passent très facilement à jj et en deviennent souvent de fervents promoteurs. Ce sont eux qui comprennent le mieux la puissance d’un outil fort pour manipuler le graphe de commits. Pour référence, je suis l’un des mainteneurs de jj, et je pense que c’est un outil remarquablement bien conçu. Cela vaudrait le coup de l’essayer quelques jours, même sans Magit

  • Voici quelques liens à ce sujet. Un article qui explique bien le workflow Megamerge : https://v5.chriskrycho.com/journal/jujutsu-megamerges-and-jj-absorb/, https://ofcr.se/jujutsu-merge-workflow, ainsi que le meilleur TUI de très haut niveau autour de la CLI jj : https://github.com/idursun/jjui

  • Je me demande quel est le « concept central » de Jujutsu. Par rapport au fait que Git est le standard de l’industrie, j’ai du mal à voir une raison suffisamment forte d’utiliser Jujutsu. Je trouve les concepts intéressants, mais s’il y avait un angle marketing plus clair, son potentiel d’adoption serait plus grand. Le plus gros défaut de Git, c’est d’être beaucoup trop hostile aux non-initiés — jargon, manque de découvrabilité, peu de frontends GUI convaincants, etc. — donc je pense qu’il y a un vrai potentiel pour un VCS plus accueillant pour les débutants

  • Je suis passé de Magit à jujutsu. Le grand changement, c’est qu’empiler les PR est devenu bien plus facile, et j’ai pris l’habitude de découper mes changements en unités plus petites, en relevant mon exigence sur ce qui « vaut la peine d’être envoyé ». Globalement, l’expérience est positive, mais si Magit vous convient déjà très bien, il n’y a pas d’avantage décisif. Cela dit, grâce à https://github.com/bolivier/jj-mode.el, on peut aussi très bien utiliser jj dans Emacs

• Je trouve cela intéressant. Pourtant, malgré une activité en ligne assez soutenue, c’est la première fois que j’entends parler de Jujutsu. J’aime l’idée d’offrir un meilleur VCS tout en utilisant Git comme backend. L’une des raisons est qu’on peut toujours sauvegarder et partager via Github-Gitlab. Fossil et Bitkeeper sont aussi séduisants, mais ils ne sont pas « suffisamment » meilleurs que git pour surmonter les effets de réseau de git. Je vais devoir essayer un peu Jujutsu. Je ne sais pas si je continuerai à l’utiliser, mais j’espère que ce sera meilleur que je ne l’imagine