Tutorial de Jujutsu do Evan

• Um tutorial estruturado para que pessoas com experiência em Git possam aprender de forma concisa o Jujutsu(jj), um sistema de controle de versão simples e poderoso
• Para leitores que, antes de começar, queiram entender por que usar Jujutsu, há um artigo introdutório sobre Jujutsu separado
• Também indica alternativas adequadas ao nível do leitor, como um guia introdutório em tom de conversa, a documentação oficial detalhada e materiais para iniciantes em controle de versão
• Foi escrito diretamente por Evan Martin, que decidiu cuidadosamente a escolha e a omissão dos temas, além da ordem de apresentação
• IA não foi usada para escrever o texto; depois que a maior parte estava pronta, ela foi usada apenas para verificar erros

---

Público-alvo e caminho de aprendizado

• Jujutsu é um sistema de controle de versão simples e poderoso; no tutorial, ele será chamado de jj daqui em diante
• Oferece um fluxo de aprendizado conciso, focado no essencial, para leitores familiarizados com Git
• Para começar a aprender imediatamente, acesse iniciar o tutorial; para entender primeiro os motivos para adotá-lo, consulte o artigo introdutório sobre Jujutsu

Materiais alternativos por perfil de leitor

• Se a abordagem deste tutorial não for a ideal para você, é possível escolher os materiais abaixo conforme seu nível de experiência e preferência
  • Steve's Jujutsu tutorial: o material introdutório mais recomendado, estruturado em tom de conversa
  • Jujutsu documentation: oferece um tutorial oficial que trata de mais detalhes desde o início
  • Jujutsu for Everyone: voltado a leitores sem experiência prévia com controle de versão

Escrita direta e escopo de uso de IA

• Todo o texto foi escrito diretamente por Evan Martin, com decisões humanas cuidadosas sobre o que incluir ou omitir e em que ordem organizar o conteúdo
• IA não foi usada para criar o texto; ela foi utilizada apenas para verificar erros depois que a maior parte já havia sido escrita

[GN⁺]

Comentários no Lobste.rs

• Para ser sincero, arriscando minha reputação: usei jj por cerca de uma semana, mas no fim acabei pedindo ajuda a um LLM para reduzir a dor de lidar diretamente com Git, e também não senti que ele substituísse bem o meu fluxo de trabalho atual.
  No dia a dia, uso basicamente git checkout, git add, git commit e git push, e quase não enfrento os problemas citados nos posts de divulgação — índice, stash, vários tipos de reset, rebase em andamento e undo inconsistente — nem costumo trabalhar muito com monorepos.
  Fico curioso para saber quem é o público-alvo principal do Jujutsu e quanto tempo levou para vocês ficarem proficientes em jj; da próxima vez, quero investir pelo menos esse período.

  • Fico curioso para saber exatamente que tipo de tarefa você pede ao LLM para ajudar.
    Eu também costumo evitar qualquer coisa além das operações básicas no Git; em vez de fazer stash e trocar de branch, eu clonava o repositório de novo em outro lugar, e em vez de selecionar só as mudanças relevantes para o commit, fazia commit de tudo com git add --all ou revertia as mudanças no editor, fazia o commit e depois reaplicava.
    No trabalho, usei Mercurial por 7 anos, então eu tinha um contexto que facilitou a adaptação ao jj, mas agora reposicionar commits e gerenciar várias mudanças ficou simples, e passei a encarar ativamente tarefas complexas que antes eu teria contornado por instinto.
  • A perspectiva muda dependendo de para que você usa um sistema de controle de versão (VCS).
    Se for só para registrar snapshots ocasionais de código desenvolvido de forma linear, esses comandos bastam; um VCS completo pode até ser exagero, e talvez Dropbox já resolva.
    Para mim, um VCS é uma ferramenta para construir uma narrativa que mostra como pensei sobre o código e sua hierarquia; o leitor principal são meus colegas, e o leitor secundário sou eu daqui a 10 anos. jj me permite lidar com isso com muito menos atrito.
  • Não tem problema pedir ajuda a um LLM; eu também fiz isso até aprender os comandos básicos de que precisava.
    Li alguns guias do começo ao fim para entender os fundamentos dos termos e recursos, e usei de forma consistente em projetos pessoais por alguns dias; com isso, fiquei bem mais à vontade nas tarefas básicas e minha forma de enxergar VCS também mudou.
    Ao fazer uma refatoração ou desenvolver um recurso grande, primeiro implemento até o objetivo final e depois divido em mudanças pequenas, fáceis de revisar e com justificativas claras, como “corrigir todos os avisos do eslint”, “refatorar para expor a função”, “migrar o chamador A para a nova função” e “adicionar novo recurso”. jj split é perfeito para isso, e só esse recurso já é motivo suficiente para usar jj.
    Por outro lado, git stash é difícil para lidar com vários stashes e tem muitas armadilhas perigosas de usabilidade, inclusive a possibilidade de perder o código salvo em caso de conflito. Incorporar feedback de PR em um commit mais antigo e depois fazer rebase dos commits ou PRs acima também é quase um pesadelo, especialmente em PRs empilhados: não há indicação de progresso, e é difícil pausar no meio ou remontar a pilha. Por isso, ainda uso Graphite para gerenciar PRs empilhados.
  • O maior benefício que obtive com jj foi a forma como ele lida com rebase.
    Um doutorando em química orgânica desenvolveu por 4 anos um branch para o trabalho de um artigo sem fazer merge nem rebase, e ele estava milhares de commits atrás de main quando precisou mesclar antes da defesa. Como havia conflitos em quase todos os commits, no Git isso levaria 1 ou 2 semanas; se no terceiro dia surgisse um bug urgente, seria preciso interromper o rebase, corrigir o bug e começar tudo de novo. E, quando terminasse 3 semanas depois, ainda teria de fazer outro rebase para acompanhar o main mais recente.
    No jj, conflitos de merge são objetos de primeira classe, então você pode resolvê-los quando tiver tempo, e mesmo que vá para um novo commit no meio do processo para corrigir um bug urgente, não perde o progresso. Consegui terminar em um dia um rebase que levaria uma semana no Git; em uma ocasião, encontrei uma sequência de 200 commits que, quando combinados, não mudavam nada, e descartei tudo em menos de um minuto, depois de dois dias lidando com dezenas de milhares de linhas de conflitos. Mesmo durante um rebase, é possível atualizar main e mover o branch em que se está trabalhando para cima do main mais recente.

• Para mim, que estou tão acostumado com Git que só preciso consultar comandos de vez em quando, este texto foi a primeira introdução ao Jujutsu que achei interessante.
  Os textos anteriores geralmente começavam com algo como “você pode se livrar da horrível interface de linha de comando do Git”; embora eu entenda as peculiaridades do Git e as dificuldades de outras pessoas, esse tipo de formulação me fazia ver o Jujutsu como algo tão alheio a mim quanto um romance romântico ou um beef vindaloo.

  • O motivo de ser difícil explicar o prazer de usar jj é que características implícitas que eu achava óbvias em qualquer VCS na verdade não são, e as operações atômicas são muito mais simples.
    Como é difícil criar uma boa frase de divulgação, no fim “não é Git” acaba tomando conta de toda a explicação; eu mesmo também não consigo explicar isso direito.
  • No Git, usando a GUI Sublime Merge e alguns comandos personalizados, dá para resolver quase todos os problemas mencionados aqui.
    Ao contrário de outras GUIs para Git, ela segue os comandos reais do Git tanto quanto possível, substituindo apenas a sintaxe difícil por menus e botões, e também não esconde os comandos correspondentes a cada ação: registra tudo na barra de status. Se sair um Sublime JJ, eu mudo na hora.
  • A expressão que me fez querer experimentar jj foi Git sempre em estado de rebase interativo.