Jujutsu para todos

• Este documento é um tutorial para iniciantes que ensina Jujutsu (VCS) em uma estrutura de níveis passo a passo, para que até quem não tem experiência com Git consiga acompanhar
• Parte do uso de terminal, mas cobre desde o básico do terminal; os principais comandos são explicados com foco em Linux/macOS, e para usuários de Windows é recomendado WSL
• O fluxo de aprendizado é estruturado para consolidar fundamentos, colaboração e resolução de problemas nos níveis 1 a 3, e depois expandir para reescrita de histórico e workflows avançados nos níveis superiores
• Para quando o estado sair do controle durante o tutorial, ele oferece um ambiente de aprendizado reproduzível com um script de reset para voltar ao ponto inicial de cada capítulo
• Sobre por que usar Jujutsu em vez de Git, o texto apresenta como base a compatibilidade com Git, a redução da dificuldade de aprendizado e os recursos avançados, e está sendo atualizado com base no Jujutsu 0.32 mais recente

---

Introdução (Introduction)

• Este tutorial é um material introdutório voltado para usuários que estão usando Jujutsu pela primeira vez
• Oferece conteúdo centrado em iniciantes para complementar a limitação dos materiais existentes de Jujutsu, que costumam focar na migração de usuários experientes de Git
• O uso de terminal é a base, inclui um capítulo de fundamentos do terminal, e para usuários de Windows recomenda-se o uso de WSL

Como ler este tutorial (How to read this tutorial)

• O conteúdo é organizado em níveis, com um desenho de aprendizado em que você deve praticar de fato após concluir cada nível antes de avançar para o próximo
• Se o objetivo for colaboração, é recomendável fazer os níveis 1 e 2 em sequência
• Visão geral dos níveis
  • Nível 1: fornece o conjunto mínimo para começar no trabalho individual, adequado ao nível de um estudante que gerencia tarefas sozinho
  • Nível 2: o conjunto mínimo para colaboração, necessário para projetos em equipe de estudantes e para desenvolvedores no trabalho
  • Nível 3: base de resolução de problemas, como conflitos e recuperação, equivalente ao nível médio de proficiência de um desenvolvedor
  • Nível 4: reescrita de histórico para construir um histórico limpo, necessária para atender aos critérios de qualidade de alguns projetos
  • Nível 5: boosters de produtividade, workflows avançados, CLI pouco comum e teoria, etapa de mestre em Jujutsu
  • Nível 6: tópicos situacionais como tags, submódulos e workspaces; recomendado consultar quando necessário

Atalhos de teclado (Keyboard shortcuts)

• Suporte à navegação entre capítulos com as setas esquerda e direita
• Suporte a busca no livro com S ou /
• ? mostra a ajuda, e Esc permite ocultá-la

Redefinir seu progresso (Reset your progress)

• Como o estado do repositório de exemplo se conecta ao próximo capítulo, perder esse estado pode bloquear o progresso
• Para resolver isso, é fornecido um script reset.sh que restaura ao ponto inicial do capítulo
• No início de cada capítulo há o comando exato de reset, permitindo reproduzir tudo com copiar e colar
• Recomenda-se revisar o conteúdo do script antes de executá-lo; na prática, ele faz operações simples, no nível de um conjunto de comandos manuais
• Principais características do script
  • Bloqueia a influência das configurações do usuário com JJ_CONFIG=/dev/null
  • Cria o repositório de exemplo, faz a integração com Git em colocação (colocate), configura informações do usuário e reconstrói cenários contínuos como commit/push/fetch/rebase
  • Foi projetado para receber palavras-chave de cada capítulo como argumento e encerrar com sucesso naquele ponto específico

Mantenha-se atualizado (Stay up to date)

• O tutorial e o Jujutsu estão em evolução contínua, e você pode receber avisos sobre grandes mudanças assinando os Releases do repositório do tutorial
• O tutorial declara estar atualizado com base no Jujutsu 0.32 (agosto de 2025)
• Também oferece instruções para configurar notificações de atualização no GitHub em Watch → Custom → Releases

O que é controle de versão e por que usá-lo? (What is version control and why use it?)

• É uma forma de gerenciar o acúmulo incremental de trabalho, aplicável não só a software, mas também à escrita de documentos como Typst
• Permite voltar a estados anteriores e oferece suporte seguro para o trabalho simultâneo de várias pessoas
• Quando é preciso uma ferramenta de controle mais precisa do que backups comuns ou editores colaborativos, o Jujutsu é uma boa opção

Por que Jujutsu em vez de Git? (Why Jujutsu instead of Git?)

• Compatibilidade com Git: oferece interoperabilidade sem perdas com repositórios Git existentes, e permite aproveitar praticamente como estão a maioria das ferramentas integradas ao Git
• Facilidade de aprendizado: em comparação com a UI complexa e pouco intuitiva do Git, o Jujutsu oferece as mesmas funções com menor complexidade
• Funcionalidade mais poderosa: além de ser fácil de aprender, oferece muitos recursos para power users, garantindo expansibilidade de workflow
• Desvantagens e pontos a considerar
  • Nas conversas, existe a carga de fazer o mapeamento conceitual com uma cultura centrada em termos do Git; isso pode ser mitigado ao convencer colegas
  • Por ser relativamente novo, há casos em que alguns recursos do Git ainda não estão incluídos; quando necessário, é possível fazer fallback para uso direto do Git
  • A CLI ainda está em processo de estabilização, então alguns comandos podem mudar; recomenda-se acompanhar essas mudanças assinando os releases do tutorial

Progresso do aprendizado (Completed & Next)

• No momento, ele é estruturado principalmente em torno dos níveis 1 a 3 para que o leitor assimile um fluxo prático de tarefas (instalação → inicialização → log/commit → remoto/push·clone → branch/merge → rebase → navegação → desfazer/recuperação → resolução de conflitos → organização)
• Para os níveis superiores, apresenta uma estratégia de proficiência gradual, com aprendizado adicional de reescrita, workflows avançados e tópicos raros

[GN⁺]

Comentários do Hacker News

• Acho que já vi dezenas de artigos elogiando o jj. Este tutorial também é parecido, mas agora que já li bastante sobre os pontos positivos, passei a me interessar mais pelas desvantagens e incômodos. Quando usei o jj, vi prós e contras. Costumo usar bastante um workflow em que compartilho branches com colegas e vou empilhando commits, mas no jj isso foi mais incômodo do que no git porque não há branches nomeados (mesmo usando o alias tug). A seção “Tracking remote bookmarks” do tutorial também ainda me parece desconfortável. Outra coisa que me incomodou foi que o jj não consegue usar clone leve como o git clone --filter=blob:none, então fiquei curioso para saber se isso já foi corrigido

  • O jj tem branches nomeados, e no jj eles são chamados de “bookmarks”. Ao rastrear um remote bookmark, o local é sincronizado com o remoto via jj git fetch

  • Uma das coisas que me deram trabalho foi que o jj às vezes parecia perder minhas mudanças aleatoriamente. Eu estava trabalhando no Cursor e não estava mutando o repositório com jj (só fazia coisas como jj status e jj log), mas depois eu via que minhas mudanças tinham sumido, e às vezes aparecia a mensagem "stale workspace". Não sei se isso era por causa da IDE ou de um monorepo gigante, mas foi realmente doloroso. Ainda assim, gosto bastante da flexibilidade do jj

  • Há uma discussão em https://github.com/jj-vcs/jj/discussions/3549 sobre como simplificar um pouco mais o workflow com tug

  • Dizer que o jj não tem branches nomeados está errado. Você precisa defini-los manualmente com algo como jj branch set -r@ XYZ, o que é um pouco incômodo, mas só precisa ser feito uma vez na hora de fazer push. Ou então dá para mover a branch com jj git push --named XYZ=@

  • O fato de o jj ainda não suportar clone leve (git clone --filter=blob:none) continua sem solução

• Foi dito que “Jujutsu é mais poderoso que Git”, mas não há explicação concreta sobre em que sentido ele é mais poderoso, então fico me perguntando por que eu deveria usá-lo. Isso parece só floreio retórico

  • Sou o autor do tutorial. Como o público-alvo são iniciantes, uma comparação detalhada com Git não teria sido apropriada. A complexidade da UI do Git muitas vezes é justificada por sua “potência”, então quis apenas acrescentar essa afirmação para mostrar aos usuários que, com o Jujutsu ser mais fácil de aprender, eles não estariam perdendo recursos

  • Por exemplo, você cria uma nova branch a partir da Main e planeja depois enviá-la como PR. Vai acumulando vários commits e depois percebe que precisa mudar o commit 1; basta editar o 1 e salvar, e todos os outros commits são rebaseados automaticamente para o estado mais recente. Mesmo depois do PR, se quiser alterar o commit 3, é só editar aquele commit e fazer push. Fazer esse tipo de coisa diretamente no Git é realmente difícil. Meus colegas adoram PRs divididos em vários commits

  • Penso mais ou menos da mesma forma. No geral sinto que as UIs de Git deixam a desejar, então estou disposto a usar jj com certo grau de confiança. Mas seria melhor se houvesse uma demonstração concreta de “por que é mais fácil, mais poderoso ou mais conveniente”

  • Um exemplo é que você pode registrar um merge conflict como um item único e resolvê-lo depois: https://jj-vcs.github.io/jj/latest/conflicts/

• Voltei a usar JJ recentemente e ele melhorou muito, então estou usando com prazer. Quando tentei no começo, havia muitas arestas e era cansativo, mas acho que o JJ faz parte de uma excelente “nova onda” recente de tooling. Também escrevi sobre isso no meu blog: https://pdx.su/blog/2025-08-13-the-quiet-software-tooling-renaissance/

  • Ótimo texto. Acho que o padrão das ferramentas de desenvolvimento realmente subiu muito nos últimos anos. Rust também faz parte dessa mudança

  • Que bom ver que você também usa e gosta do mise. mise, jj (e o absolutamente incrível TUI jjui) e o uv para Python são todos revolucionários. Acho essas ferramentas realmente belas

  • Eu definitivamente adicionaria o nushell aqui

  • Bun também está na linha de frente dessa revolução de tooling

• Excelente trabalho! Estou usando só Jujutsu há quase 5 meses, substituindo completamente o git. Na prática, durante esse período executei Git 52 vezes (11 delas só com --help), enquanto usei Jujutsu 582 vezes. Sem precisar se adaptar a um workflow específico, o Jujutsu é flexível o bastante para suportar quase qualquer workflow. Mesmo usando como se fosse git, você pode mover commits e branches livremente (sem precisar fazer stash), fazer rebase com facilidade (talvez isso seja normal para especialistas em git, mas sou muito grato por conseguir fazer isso direto, sem depender das ferramentas git do VSCode) e focar no trabalho sem a parte dolorosa do VCS. Vale notar que o histórico do trabalho continua registrado no repositório git como antes, então continua compatível com outras ferramentas de git. Ou seja, eu posso usar algo diferente mesmo que meus colegas não mudem de VCS. Há alguns pontos fracos em tags, submodules e LFS, mas ainda assim vale muito a pena experimentar

  • Fico curioso sobre qual seria o equivalente em jj para git branch --set-upstream-to

  • Se você usar o jjui, quase nunca mais vai tocar nos comandos do jj. É realmente impressionante

• Jujutsu é realmente muito bom. Testei há alguns meses e até escrevi alguns textos sobre ele (este aqui), e desde então continuo usando. No geral é uma experiência muito “consistente”. Na verdade eu era uma pessoa que já usava git sem problemas, mas no jj tudo gira em torno de alguns princípios básicos, e você pode combiná-los como quiser para mudar históricos complexos com facilidade. Eu trabalhava muito no estilo “stash-first”, e o jj é muito mais agradável que git graças ao rastreamento automático de mudanças, à movimentação livre de alterações e afins. Rebase e resolução de conflitos também são muito melhores (especialmente em workflows estilo stash). Recomendo fortemente, e o esforço para migrar é bem pequeno

• Pessoalmente, não gosto muito da abordagem de adicionar uma nova camada em cima do git. Entendo que é difícil quebrar a hegemonia do git, mas acho que construir sobre uma base totalmente nova seria muito mais poderoso e livre

• Usei jj por cerca de um mês e depois voltei para git por causa de um projeto específico no trabalho. Gostei bastante do jj, mas não foi nada além disso. Só que, poucas horas depois de voltar para git, senti muita falta das conveniências do jj: https://blog.nawaz.org/posts/2025/Aug/the-jujutsu-effect/

  • Fico curioso sobre o que exatamente quer dizer com “não foi nada além disso”

  • A ideia é que você só percebe o valor real depois que perde

• Eu gostaria de ler mais sobre “Jutustsu for Git experts”. Por exemplo, quero saber se commitar conflitos não vai atrapalhar meu git rerere, ou se existe no jj uma maneira prática de implementar um conjunto de patches em duas etapas, já que no git eu gosto de usar git add -p para staging parcial de um patch. Quero evitar timestamps corrompidos ou rebuilds desnecessários em sistemas de build

  • Vou responder com o workflow mais usado no jj (o “squash workflow”). Você altera livremente no top commit, que é o diretório de trabalho, e quando quiser “fazer staging”, faz squash para baixo no commit inferior (ou seja, um nível abaixo), seja de tudo ou só parte com -i. Também dá para indicar outro commit e fazer squash nele com squash --into

  • 1. O jj não usa git rerere, então essa pergunta fica um pouco fora do alvo. 2. @ é o workspace e @- é o commit em que você está trabalhando. Com jj squash -i você pode mover interativamente de volta para @ só a parte do diff que quiser

  • Embora eu concorde que a distinção stage/unstage seja desnecessária, acho curioso o quanto as pessoas gostam de “fazer staging só das partes boas do patch”. Combinando git worktree, git diff, vi e git apply dá para obter algo parecido sem staging, mas é realmente trabalhoso. Mesmo no mercurial 7.1 ainda não há adição interativa, então fora alguns truques via worktree não há alternativa

• Tenho visto Jujutsu ser mencionado recentemente, mas ainda não entrei nos workflows concretos. Fico curioso se o Jujutsu tem alguma vantagem especial sobre o Emacs Magit. A maioria das UIs de Git que usei até hoje era fraca, mas o Magit aumentou muito minha produtividade com git e me fez sentir a “mágica” do git. Queria entender se o Jujutsu está tentando competir com essa experiência ou se o objetivo é ser uma alternativa às UIs de git existentes, que de fato são bastante fracas

  • Jujutsu não é apenas uma UI de git; na verdade, ele é até fraco como UI de git (falta suporte a tags, submodules etc.). É um VCS totalmente novo, mas que usa git como backend. Se o git trouxe “cheap branch” em relação ao SVN, o JJ traz “cheap rebase”. Conflitos não interrompem todo o trabalho, e rebase, organização da estrutura de commits etc. ficam realmente confortáveis. Se você já usou stacked diffs, isso vai parecer familiar, e PRs com stacked diffs no jj saem quase sem esforço

  • Se você já usa bastante o Magit, os conceitos básicos do jj provavelmente também vão te atrair. O jj permite acrobacias com commits que antes pareciam impossíveis (por exemplo, fazer rebase de 2 folhas de um merge octopus de 5 vias mantendo conflitos sem resolver). Isso inclusive é uma técnica que criei, chamada “Mega Merge”. Magit e jj têm semelhanças, e acho que a “mágica do git” na verdade vem da “linguagem de design” da ferramenta. O Git é só a camada física de armazenamento tanto para Magit quanto para jj, mas eles diferem muito em algoritmos, UX e conceitos. Usuários de Magit tendem a sofrer menos choque com jj, mas usuários avançados da linha de comando do Git migram para jj com enorme facilidade e acabam virando grandes evangelizadores. São pessoas que entendem melhor do que ninguém o poder de uma ferramenta forte para manipular grafos de commits. Aliás, sou um dos mantenedores do jj, e acho que é uma ferramenta muito bem-feita. Eu recomendaria experimentar por alguns dias, sem Magit

  • Aqui estão alguns links relacionados. Um texto que explica bem o workflow de Megamerge: https://v5.chriskrycho.com/journal/jujutsu-megamerges-and-jj-absorb/, https://ofcr.se/jujutsu-merge-workflow, e o melhor TUI para envolver a CLI do jj: https://github.com/idursun/jjui

  • Fico curioso sobre qual seria o “conceito central” do Jujutsu. Em comparação com o fato de o Git ser padrão da indústria, ainda não sinto que haja um motivo forte o bastante para usar Jujutsu. Acho os conceitos interessantes, mas um posicionamento de marketing mais claro talvez aumentasse muito o potencial de adoção. A maior fraqueza do Git é ser muito hostil para quem vem de fora (terminologia, baixa descobribilidade, falta de bons frontends GUI etc.), então vejo bastante potencial em um VCS amigável para iniciantes

  • Migrei do Magit para o jujutsu. O que mudou foi que ficou muito mais fácil empilhar PRs, e peguei o hábito de dividir mudanças em unidades menores, então meu critério para algo “digno de enviar” ficou mais rigoroso. No geral foi uma experiência positiva, mas se o Magit já funciona muito bem para você, não há uma vantagem especial. Ainda assim, graças ao https://github.com/bolivier/jj-mode.el, também dá para usar jj tranquilamente no Emacs

• Achei interessante. Mesmo sendo bem ativo online, esta foi a primeira vez que ouvi falar de Jujutsu. Gosto da ideia de oferecer um VCS melhor usando Git como backend. Um dos motivos é que assim ainda dá para fazer backup e compartilhar via Github-Gitlab. Fossil e Bitkeeper também são atraentes, mas não são “suficientemente” melhores que git a ponto de superar o efeito de rede do git. Acho que vou brincar um pouco com o Jujutsu. Não sei se vou continuar usando, mas espero que ele seja melhor do que imagino