Artigo original: How to Animate Your Git Commit History with git-story

Muitas vezes, é útil para os desenvolvedores visualizarem aspectos de seus projetos de código. Especialmente em sistemas de controle de versão como o Git, onde é essencial entender o fluxo de trabalho da equipe.

Uma maneira de abordar isso no Git é desenhar um grafo como o que você viu na imagem inicial.

Você, provavelmente, já encontrou imagens como essa quando estava aprendendo como usar o Git (texto em inglês).

Esse grafo mostra um exemplo de histórico de revisões em um repositório do Git.

No Git, o histórico de revisões é representado como um DAG, ou Directed Acyclic Graph (grafo acíclico direcionado), que é um tipo de grafo de rede. Cada revisão é exibida como um círculo e as revisões são encadeadas usando setas. Cada seta aponta de uma revisão para sua antecessora imediata.

Na maioria das vezes, se você desejar um grafo desses, precisa desenhá-lo (manual ou digitalmente) – o que leva tempo e esforço. Além disso, esses grafos são estáticos e, em certos casos, seria muito mais interessante animar a progressão das revisões em um vídeo.

Por esses motivos, criei o Git Story (texto em inglês), que permite gerar facilmente vídeos em mp4 apresentando o layout e a progressão do histórico do Git, com apenas um único comando: git-story.

Como visualizar o histórico de revisões do Git

No Git, uma revisão também é conhecida como commit. Ela representa um conjunto de alterações ao conteúdo feitas em um momento específico por uma pessoa específica.

Existem vários componentes adicionais que nos ajudam a entender visualmente nosso histórico do Git.

Propriedades dos commit

Ao fazer um commit no Git, a legibilidade é importante. Portanto, é uma prática recomendada deixar uma mensagem no commit (texto em inglês) de forma clara, descrevendo sua alteração. Isso ajuda outros desenvolvedores que visualizam o histórico de commits a entender o propósito de cada alteração.

O ID do commit é um identificador exclusivo para cada commit, gerado especificamente a partir de seu conteúdo. Como usuário do Git, você provavelmente já viu que muitos comandos dele aceitam como argumento um ID de commit total ou parcial. Por esse motivo, ter IDs de commit disponíveis nas visualizações do Git pode ser muito útil.

Referências: branches, HEAD e tags

Ao visualizar o histórico do Git, também é útil saber onde você está. E uma referência no Git te ajuda a entender como os commits estão organizados no seu repositório.

Referências são rótulos (labels) que o Git anexa a commits específicos. Nomes de branch, Git HEAD (texto em inglês) e tags são todos exemplos de referências. Você pode pensar em um referência como um nome legível para nós, humanos, que aponta para um commit específico.

Vídeo gerado pelo Git Story

O Git Story (texto em inglês) analisa todas essas informações para você – commits, relacionamentos e referências – e as anima em um vídeo .mp4. A melhor parte é que tudo o que você precisa fazer é navegar no terminal até o seu projeto e executar o comando git-story.

Abaixo temos um exemplo de uma animação de vídeo gerada pelo Git Story:

Por que escrevi o Git Story em Python

Eu escolhi escrever Git Story em Python, pois existem duas bibliotecas muito úteis que alimentam este projeto.

GitPython

A primeira é chamada GitPython (texto em inglês), que é um pacote Python que fornece acesso a dados de repositórios do Git através de um conjunto de métodos práticos. É assim que o Git Story acessa os dados do repositório local do Git para animá-lo:

import git

repo = git.Repo(search_parent_directories=True)

Isso cria um objeto do repositório na memória do programa em Python que permite acesso aos objetos subjacentes do Git, além de suas propriedades. Uma lista de commits pode ser acessada da seguinte forma:

commits = list(repo.iter_commits(REF))

# Isso puxa uma lista de commits, de trás para frente, de REF
# REF pode ser um nome de branch, tag, HEAD ou uma ID de um commit

A iteração na lista de commits permite o acesso às propriedades de cada commit, que são usadas na próxima etapa para gerar a animação.

Manim

A segunda dependência é chamada Manim (texto em inglês), que é usada para gerar vídeos de matemática animados usando uma API em Python. O Manim facilita muito a criação de objetos em Python que representam linhas, formas, textos e equações e a colocação desses objetos em uma animação.

O Git Story usa o Manim para desenhar os círculos, as setas, os textos, e os nomes de cada branch do Git (texto em inglês) e cada referência que representa o intervalo do seu histórico do Git obtido pelo GitPython.

Esse é um código que mostra como o Manim é usado para criar um círculo vermelho para cada commit:

circle = Circle(stroke_color=commitFill, fill_color=commitFill, fill_opacity=0.25)

Aqui vemos como o Manim é usado para criar as setas entre os commits:

arrow = Arrow(start=RIGHT, end=LEFT, color=self.fontColor).next_to(circle, LEFT, buff=0)

Por fim, aqui vemos como esses objetos são adicionados a uma animação:

self.play(Create(circle), Create(arrow))

Como instalar o Git Story

  1. Instale o manim e suas dependências em seu sistema operacional
  2. Instale o GitPython :$ pip3 install gitpython
  3. Instale o git-story: $ pip3 install git-story

Como usar o Git Story

  1. Abra um terminal de linha de comando
  2. Navegue até a pasta raiz do seu projeto Git usando cd
  3. Execute o comando: git-story

A execução deste comando gerará uma animação de vídeo .mp4 dos 8 commits mais recentes em seu repositório Git. O arquivo de vídeo será colocado no diretório atual, no caminho ./git-story_media/videos.

Como personalizar a animação do Git Story

O Git Story inclui várias formas de modificar como seu repositório do Git é representado no vídeo gerado. Você faz isso por meio de opções e flags da linha de comando.

Para especificar o número de commits para animar, por exemplo, use a opção --commits=X, onde X é o número de commits que você deseja mostrar.

Você também pode querer começar a animar a partir de um commit específico, que não o HEAD. Para isso, você pode usar a opção --commit-id=ref para selecionar o commit inicial pelo qual deseja começar, de trás para frente. Em vez de ref, você também pode substituir por um ID total ou parcial de um commit, nome de branch ou tag do Git (texto em inglês).

Você pode usar a flag --reverse para animar os commits do mais novo para o mais antigo, que é a ordem cronológica reversa, para corresponder melhor à saída de log do Git (texto em inglês).

Experimente a flag --low-quality para acelerar o tempo de geração da animação durante o teste. Quando estiver satisfeito com a aparência da sua animação, remova a flag e execute o comando novamente para obter uma versão final de melhor qualidade.

Se preferir um esquema de cores claras em vez do padrão escuro, você pode especificar a flag --light-mode.

Para fins de apresentação, você pode adicionar um título de introdução, logotipo e conclusão à sua animação. Você pode fazer isso com as seguintes opções:

$ git-story --show-intro --title "My Git Repo" --show-outro --outro-top-text "My Git Repo" --outro-bottom-text "Thanks for watching!" --logo path/to/logo.png

Use a opção --media-dir=path/to/output para definir o caminho do vídeo a ser gerado. Isso é útil se você não quiser que arquivos extras sejam criados dentro do seu projeto.

Finalmente, você pode querer testar a flag --invert-branches se o histórico de commits do Git tiver vários branches. Essa flag mudará a ordem em que as branches são analisadas, o que altera a orientação da branch no vídeo gerado. Algumas animações ficarão melhores com essa flag definida e outras não.

Aqui está um exemplo final que mostra a aparência do vídeo quando existem várias branches no intervalo de commits:

Resumo

Git Story é uma ferramenta de linha de comando que escrevi em Python para facilitar a criação de animações de vídeo do seu histórico de commits do Git. As dependências incluem Manim e GitPython.

A animação exibe o conjunto desejado de commits e seus relacionamentos, juntamente com os nomes das branches, o commit HEAD e as tags.

O Git Story tem uma variedade de flags e opções de linha de comando que permitem personalizar a animação. Execute o comando git-story -h para exibir a lista completa de opções disponíveis.

Sinta-se à vontade para enviar um e-mail para o autor deste artigo com comentários, perguntas ou sugestões: jacob@initialcommit.io.

Pull requests também são muito bem-vindos à página do Git Story no GitHub.

Obrigado pela ler e uma boa programação para você!