Talvez uma das histórias mais conhecidas do mundo Open Source é o nascimento do Git: Linus Torvalds precisava de um sistema de controle de versão para o kernel Linux e nos deu o Git. Enquanto até hoje ele é o mantenedor do kernel, ele foi o mantenedor do Git por apenas três meses, de abril a julho de 2005. Desde então, o Git é mantido por Junio Hamano.

Mesmo após 20 anos desde a troca de liderança, o Git ainda é lembrado como a segunda obra-prima de Linus Torvalds. Pessoalmente, acredito que o que torna o Git excelente é seu elegante núcleo que existe desde sua primeira versão que seja o principal presente que Linus nos deu.

Porém, o quão usável era o Git quando o Torvalds ainda era o mantenedor? Veremos isso aqui, olhando para duas versões do Git:

1. O primeiro commit
2. A última release feita pelo Torvalds

Então, vamos ver o que aconteceu nesse momento da história do Git.

Setup

Voltemos no tempo. Minha máquina do tempo é o Ubuntu 7.10 Gutsy Gibbon, lançado in 2007. Ele é velho o suficiente para ter pacotes nas versões que o Git antigo precisa e, por sorte, encontrei uma imagem Docker para isso. Eu realmente queria usá-lo no meu Linux moderno, porém, não é tão fácil compilá-lo por conta dessas incompatibilidades de bibliotecas.

É bem fácil obter o código-fonte das versões antigas do Git. Ele é, obviamente, versionado com Git e suas primeiras versões ficarão guardadas para sempre em seu histórico:

git clone git@github.com:git/git.git
cd git

# Listando os commits do mais velho para o mais novo. Queremos o primeiro
git log --reverse

# Listando as versões anteriores à 1.0. Queremos a última lançada por Torvalds
git tag --list 'v0.*'

Tentaremos usar o Git antigo para versionar um simples fizzbuzz em C:

1. Primeiro commit: um código C simples apenas com #include <stdio.h> e a função main
2. Segundo commit: o laço com o print
3. Terceiro e quarto commit: commits paralelos, um adicionando fizz e o outro buzz
4. Quinto commit: merge de fizz e buzz:

Este é o grafo de commits que queremos:

*   merge
|\
| * buzz
* | fizz
|/
* for
* initial

Este é o código do fizzbuzz, escrito de uma forma que evita conflitos de merge:

#include <stdio.h>

void print(int i) {
    int fizzbuzz = 0;

    // números fizz

    if (i % 3 == 0) {
        printf("fizz");
        fizzbuzz = 1;
    }

    // números buzz

    if (i % 5 == 0) {
        printf("buzz");
        fizzbuzz = 1;
    }

    // outros números

    if (!fizzbuzz)
        printf("%d", i);
    
    putchar('\n');
}

int main() {
    int i;
    
    for (i = 0; i < 100; i++)
        print(i);

    return 0;
}

Primeira versão: “o gerenciador de informações do inferno”

Voltemos ao primeiro commit do Git, e83c5163. Só 9 arquivos, um Makefile e um README. Apenas 1036 linhas de código C. Havia alguns pequenos problemas no código e não foi possível compilar apenas com make. Felizmente, os problemas eram fáceis de corrigir ( aqui está o código corrigido ).

Primeira coisa estranha que notei é que ele não cria um executável chamado git. Em vez disso, ele cria 7 executáveis:

• init-db: equivalente a git init
• update-cache: equivalente a git update-index ou git-add
• show-diff: mais ou menos parecido com um git diff no diretório de trabalho
• cat-file: equivalente a git cat-file -t + git cat-file -p, redirecionando a saída para um arquivo temporário
• commit-tree: equivalente a git commit-tree
• read-tree: equivalente git read-tree
• write-tree: equivalente a git write-tree

Deles, o primeiro não existe mais, ao menos não no seu nome original. Os últimos 4 ainda existem como comandos plumbing de baixo nível.

Ok, podemos brincar com ele.

Inicializando

Primeiramente, inicializei um repositório com init-db. Ele me mostrou uma mensagem misteriosa “defaulting to private storage area”. Em vez de criar um diretório .git, ele criou um diretório .dircache contendo apenas um diretório objects parecido com o .git/objects, porém, contendo todos os diretórios 00~ff por padrão:

Adicionando um código C simples ao index

Antes de criarmos um commit, precisamos adicionar nossos arquivos à área de staging (o index). Usamos update-cache para fazer isso, da mesma como hoje fazemos com git add:

update-cache fizzbuzz.c

Podemos ver que agora temos um arquivo fac3c1271f86c06acb743615aa5b8fd3748401 dentro de .dircache/objects/88, o que significa que foi criado um objeto 88fac3c1271f86c06acb743615aa5b8fd3748401. No Git moderno poderíamos inspecioná-lo com git cat-file -p e ver os conteúdos desse objeto. Nesta primeira versão é necessário usar cat-file e ele mostra que o objeto é um blob (um conteúdo de um arquivo) e ele cria um arquivo temporário com seu conteúdo:

Um novo arquivo index foi criado dentro de .dircache, assim como temos no Git modeno. Não temos um comando para inspecioná-lo (como git status ou git ls-files). Podemos usar hexdump aqui e ele mostra que esse arquivo mapeia fizzbuzz.c ao blob criado. Então, parece estar tudo funcionando.

Criando um commit

Queremos agora criar um commit. Não temos git commit aqui, mas podemos fazer isso de forma manual da mesma forma que no Git moderno poderíamos fazer com git write-tree + git commit-tree ( mais infos aqui ). Essa versão já tem versões primitivas desses dois comandos, então vamos usá-los.

Podemos ver através de cat-file que o commit foi criado com sucesso. Ele é bastante similar aos commits modernos, porém, podemos ver que ele armazena as datas e horas como texto em vez de um timestamp com timezone.

Dessa forma, a sequência git add + git commit seria:

# git add fizzbuzz.c
update-cache fizzbuzz.c

# git commit -m "my commit"
echo "my commit" | commit-tree $(write-tree) -p <parent commit>

Restaurando o conteúdo

Não temos git restore, git reset ou git checkout aqui, então se quisermos obter uma versão anterior de um arquivo precisamos fazê-lo atravées de cat-file. Vamos alterar o fizzbuzz.c e tentar restaurá-lo. show-diff nos mostra o diff em relação ao index, podemos usá-lo para ver as diferenças. Então, é possível restaurar usando cat-file, mas para isso precisamos do hash do blob.

Mas e se quisermos restaurar o conteúdo de outro commit, como normalmente fazemos com git checkout? Precisamos obter o commit, depois sua tree e por fim, olhar os conteúdos da tree com hexdump, assim:

commit_content=$(cat-file <commit> | cut -d ':' -f 1)
tree_hash=$(cat $commit_content | head -n 1 | cut -d ' ' -f 2)
hexdump -C $(cat-file $tree_hash | cut -d ':' -f 1)

Em nosso setup temos apenas um arquivo, então a tree só tem uma única entrada. Desta forma, os últimos 20 bytes são o hash do blob que queremos. Se usarmos cat-file para obter esse blob, podemos renomear o arquivo como fizzbuzz.c.

blob_hash=$(tail -c 20 < $(cat-file $tree_hash | cut -d ':' -f 1) | xxd -p)
mv $(cat-file $blob_hash | cut -d ':' -f 1) fizzbuzz.c

Criando os outros commits

A única diferença próximos commits antes do merge é que eles precisam referenciar seu commit pai. Podemos fazer isso usando a mesma sequência de update-cache, write-tree e commit-tree, porém, usando -p <pai> no commit-tree, da mesma forma que no git commit-tree moderno.

Nosso histórico de commits está assim:

* buzz
| * fizz
|/
* for
* initial

Merge

Ainda não há um algoritmo de merge, temos que mesclar os arquivos manualmente e criar o commit de merge. O commit de merge é um commit com dois pais, então podemos usar a mesma sequência, mas fornecendo dois -p <parent> ao commit-tree.

Compatibilidade

Chegou a hora de saber se o repositório é compatível com um Git moderno (estou usando 2.50.1). Podemos copiar o arquivo index e o diretório objects do .dircache para um .git novo. Vamos ver o que acontece.

Ah não, todos os arquivos copiados são considerados quebrados pelo Git. git log até funciona, mas git checkout não.

HEAD e branches

Talvez você reparou que eu não mencionei nada sobre branches ou o commit atual (HEAD). E isso é porque esses conceitos não existem ainda. Nós apenas operamos a nível de objetos e index. É necessario saber o hash de cada commit.

É usável?

Nem um pouco. Mesmo se você souber bem como manipular objetos do Git, você precisará copiar os hash toda hora. É difícil de saber o que está acontecendo com esses comandos primitivos e a falta de referências torna tudo realmente difícil. Para ser um pouco mais usável você precisa escrever scripts para manipular os objetos.

A última versão do pai do Git

O primeiro commit é fácil de encontrar, mas e quanto à última versão lançada por Linus Torvalds? Precisamos ir um pouco mais fundo na história do Git e no histórico de Git do Git para encontrar o que aconteceu.

Nossa primeira pista é a mensagem “Meet the new maintainer” enviada do Linus para a lista de email do Git. Ela foi enviada em 15 de julho de 2005, apenas três meses após o primeiro commit. Podemos verificar as tags de release próximas a essa data e ver quem as gerou:

• v0.99 aponta para um commit feito pelo Junio, mas ainda assinado pelo Linus. Essa tag não tem nenhuma informação de autor porque isso ainda não tinha sido implementado, ainda ia levar alguns dias até que a informação do tagger ser introduzida aqui!
• v0.99.1 tem Linus como autor e é a última versão antes do e-mail “Meet the new maintainer”
• v0.99.2 tem Junio como autor e é assinado por ele

Dessa forma, Linus só criou duas release do Git: v0.99 (em 10 de julho) e v0.99.1 (em 15 de julho, apenas 5 dias depois). A primeira versão do Junio (v0.99.1) foi lançada apenas duas semanas depois. Vale a pena notar que v0.99.1 é a última versão com Linus como maintainer, mas não a última em que ele esteve envolvido. Na verdade, você pode ver com git log --author='Linus Torvalds' que ele enviou vários patches desde então.

v0.99.1 já tem o executável git, mas ele é apenas um script para chamar outros comandos. Você verá que essa versão é muito mais familiar. Ele cresceu bastante em tamanho, já tendo 20292 linhas de código C, 1092 linhas de código Perl e 8673 linhas de shellscripts (incluindo testes).

Da mesma forma que o primeiro commit, ele não compila na primeira tentativa. Precisei remover o git-http-push do Makefile, já que eu não precisava dele e ele estava quebrando o build.

Inicializando

Agora todos os comandos estão debaixo do comando git, da mesma forma que o Git moderno (ainda que possamos chamar eles diretamente). Também agora git init-db gera um diretório .git contendo a HEAD e o diretório refs (onde ficam as branches e tags). Nesta versão, HEAD é um symlink para a branch que ela aponta, ao contrário de outras versões mais novas do Git onde ela é um arquivo de texto puro.

Adicionando ao index and criando commits

Nesta versão, o Git já tem git add e git commit. git status existe, mas não funciona se não temos pelo menos um commit no nosso histórico. Também temos git log, mas ela não mostra o nome da branch.

Restaurando os conteúdos de um arquivo

Se tivermos um commit, git status funciona. Ele nos diz que fizzbuzz.c foi deletado, e que podemos restaurá-lo usando git checkout -f. Legal.

Criando outros commits e branches

Como já temos git add e git commit, não precisamos ficar brincando com comandos plumbing para criar novos commits. Também podemos criar novas branches com git checkout -b ou git branch e navegar entre eles usando git checkout, então essa etapa é realmente como se estivéssemos usando o Git moderno. O git checkout, porém, ainda não consegue entrar em detached HEAD.

Porém, git rev-parse, git log e git branch não mostram o conteúdo da branch atual e git-symbolic-ref também não existe ainda. A única forma que consegui descobrir a branch atual foi olhando direto o link simbólico .git/HEAD.

Merge

git merge ainda não existe, mas o README diz como fazer um merge manual usando git read-tree. Também temos um script que o Linus escreveu para tornar isso mais fácil, chamado git resolve. Internamente, ele depende do comando merge do GNU RCS, então precisamos dele instalado. Ele conseguiu mesclar as duas branches corretamente.

Compatibilidade

Aparentemente tudo parece funcionar normal quando abro este repositório com o Git 2.50. Mas este repositório é bem simples e com um único arquivo, não sei o que acontece com repositórios mais complexos.

É usável?

Se você sabe o que está fazendo, esta versão já é usável. Mas você precisa realmente saber o que está fazendo, as mensagens de erro não ajudam muito. Outros recursos importantes do Git ainda não foram implementados, então, mesmo que ele seja familiar, é necessário entender o funcionamento interno do Git para usá-lo.

Conclusão

É sempre legal ver o nascimento de algo grandioso. A primeira versão do Git era apenas um conjunto simples de utilitários para manipular alguns arquivos, mas já continha o miolo que torna o Git excelente. A última versão do Git do Torvalds já era muito mais usável e, mesmo que ainda parecesse um tanto frágil, já parecia ser usável o suficiente para ser usada por alguém que realmente sabia o que estava fazendo. Linus certamente sabia e o usou para versionar o Linux.

Ainda que o Linus Torvalds seja lembrado como o pai do Git, a última versão sob sua liderança não era exatamente o Git que conhecemos hoje em dia. Porém, é claro, isso foi um começo incrível e é impressionante o que ele e a comunidade construíram nesses três primeiros meses.

Intro

Git submodules are something that haunts me. They are a pain, but sometimes they are the only available solution. But, well, they work if used carefully.

However, not everyone use them carefully. I mean, I can’t remember how many times I needed to explain that submodules point to commits instead of branches… But I can’t blame them, it took me a some time to really understand how work, even if I used them everyday. And there are even more things that aren’t so well-known about submodules, for example, how Git merges them, as I explained here.

So, here I’ll show a situation that I once saw.

Goals

• Discourage the use of squash merge in repositories that have submodules;

• Show how squash merges can break repositories that uses submodules.

Non-Goals

• Explain how submodules work. I did that here.

• Discourage the use of squash merge in a general way. I did that here.

• Discourage the use of submodules.

The situation

Imagine this situation: you have a project A that has a project B as a submodule. Imagine that you have a feature that need to be developed in both A and B to work. Let’s assume that on both repositories you have a main branch.

A safe workflow

A safe workflow is this:

1. develop the new feature in a branch X in *B;
2. wait for review and approval of X, then merge X on B’s main;
3. develop the new feature in a branch Y in A, making it point to B’s main;
4. wait for review and approval of Y, then merge Y on A’s main;
5. deploy.

Remember submodules don’t point to branches, they point to commits. When we make Y point to B’s main we’re actually making it point to the commit that B’s main references. If are not familiar with this concept, I discussed about how submodules work here.

That is an ideal workflow, but it may be to slow as you need to wait the approval without writing the new code of Y.

A faster workflow

Waiting X to be approved and merged takes time, and sometimes we don’t want to be blocked by it. We can use that wait time to develop our new feature in A, by pointing to X instead of the B’s main:

1. develop the new feature in a branch X in B, just like before;
2. develop the new feature in a branch Y in A, making it point to X;
3. wait for review and approval of X, then merge X on B’s main;
4. make Y point to B’s main, as it now contains the new feature;
5. wait for review and approval of Y, then merge Y on A’s main;
6. deploy.

No problem in doing that. If we follow that, in step 5 the three-way merge algorithm will make A’s main point to B’s main, as I explained here.

However, step 4 is easy to forget: A works when it is pointing to X, so, it is easy to forget to make it point to B’s main after X is merged. After that, step 5 would point to X instead of B’s main:

Note that doing that code won’t break the code. A’s main will point to X, and it has the same code that it had previously plus the changes that were introduced in X. The only drawback here would be that A’s main would not be referencing the latest commit pointed by B’s main.

In fact, even though it looks wrong and it’s not the ideal situation, it won’t break anything, as after X was merged on B’s main, the commit pointed by X will be an ancestor of B’s main. This way, A would be referencing what can be considered an older version of B’s main. The order of the parent commits of a merge commit doesn’t matter here, and that’s one of the beauties of Git.

But…

But it works because the commit pointed by X is still reachable from B’s main. And this is because we performed a true merge, keeping a reference to the merged branch.

This is not what would happen if we performed a squash merge, as the squash merge is the same as the true merge except that it doesn’t keep the reference to the merged branch, as I explained here.

Then, things can break if you replace the merge in 3 by a squash merge. After merging a PR (true merge, squash merge or fast forward) on GitHub, this shows up:

It’s reasonable to click on it, as the code is already merged and you won’t need that reference anymore.

So, let’s imagine the sitation where we replaced the merge in step 3 by a squash merge and then clicked that button to delete X. Then, we proceed to step 5, where we merge Y on A’s main.

Supposing that even if the code worked for both the reviewers and the author, it will break if we try to deploy in that situation.

And it’s worse: it only works on the machines where the people who developed and reviewed the code before 5, but it won’t work on other machines! This way, both the reviewers and the developers will swear that the code works while everyone else clearly see that it is broken!

What’s happening???

Remember that when you perform a squash merge you don’t reference the commit pointed by the original branch? If you delete the original branch (that is also a reference) on GitHub or similar you’ll lose the last remaining reference to that commit on the remote repository, but you won’t lose in the machines that still have X.

When a commit is not reachable by any reference (normally, branches and tags) of its repository, it can’t be fetched as git fetch (and of course, git pull or git clone) only fetches given a reference. Not only that, but eventually that commit will be deleted as it is unreachable (see git gc). It means that the commit pointed as submodule by A’s main is lost. This way, the code will depend on something that doesn’t exist anymore! And, of course, if it depends on something that doesn’t exist it won’t work!

Conclusion

Code that only works on the developer and the reviewer machines but not on other machines is a nightmare. This is a new level of “but it works on my machine” because even if you have the exact same setup as the developer, the code will break, as the problem is a commit that doesn’t exist anymore.

So, if someone uses your code as a submodule, stopping using squash is not enough. I ask you: DISABLE the option to squash if you can on GitHub or similar. This is harmful.

Thanks for your time! I hope that this may be useful. If something is wrong, please open a issue.

Ruby é tão associada com seu framework mais famoso, Rails, que muitas pessoas esquecem o quanto incrível essa linguagem é. Quero dizer, eu conheço muita gente que diz “eu não gosto de Ruby” e quando eu pergunto o porquê, eles dizem alguma coisa sobre o Rails. Pessoalmente, considero Ruby uma das minhas linguagens de programação preferidas, e a última vez que eu encostei em algum código de Rails foi há 7 anos…

Então, se eu não uso mais Rails, o que é que eu faço com Ruby? Bem, Ruby é uma linguagem bem rica e completa, talvez até mais que sua parente mais famosa, Python (infelizmente, não posso dizer a mesma coisa sobre seu ecossistema…). E uma das coisas que eu considero que Ruby é melhor que Python é para escrever shell scripts.

Isso é, na maior parte dos casos Bash é suficiente pra mim, mas se o script começa a ficar complexo, então eu vou para Ruby. Aqui vou mostrar as principais features da linguagem para esse caso de uso.

Objetivos

• Mostrar features de Ruby que possam ser úteis para escrever shell scripts;

• Comparar Ruby com Bash e Python;

Não-objetivos

• Substituir completamente scripts Bash por scripts Ruby.

Feature 1: chamar comandos externos

A primeira coisa que você espera de uma linguagem para escrever shell scripts é chamar comandos externos. Em Ruby, você pode fazer isso usando backticks (`):

`ls`

E é isso! Você não precisa de system, popen ou similares, ou importar uma biblioteca. E se você atribuir isso a uma variável, você terá a saída do comando:

my_date=`date`

Nota: se você quiser usar system (ex: se você quer que a saída seja redirecionada para o stdout em vez de uma string) ou popen (se você quiser ler e escrever dados de ou para um subprocesso), eles também estão disponíveis em Ruby!

Feature 2: status code

Este é bem rápido: em Ruby, a variável $? contém o status code do último comando executado. Então, é bem próximo de Bash:

`true`
puts $? # 0

`false`
puts $? # 1

Feature 3: Ruby tem tipos

Ruby não é uma linguagem estaticamente tipada, mas tem tipos. Na verdade, é uma linguagem orientada a objetos e segue estritamente o paradigma de POO (mais que Python, em alguns aspectos até mais do que Java!). Bash, por outro lado, tudo é uma string, e isso leva a vários problemas de segurança…

Então, você pode tirar proveito disso:

total_lines = `wc -l my_file`.to_i # um int contendo o número de linhas de um arquivo
half = total_lines.div 2           # divisão inteira
puts `head -n #{half} my_file`     # imprime metade de um arquivo

Feature 4: construções funcionais

Ruby implementa map, select (filter), reduce, flat_map e outras operações funcionais como métodos. Então, você pode, por exemplo, aplicar um map sobre a saída de um comando:

puts `ls`.lines.map { |name| name.strip.length } # imprime os comprimentos dos nomes de arquivos.

Feature 5: casamento de regex

Regex é um tipo em Ruby, e as operações usando regex são parte da linguagem. Olhe este exemplo, em que a gente obtêm o nome da branch atual do Git chamando git branch:

current_branch_regex = /^\* (\S+)/
output_lines = `git branch`.lines
output_lines.each do |line|
  if line =~ current_branch_regex # casa a string com a regex
    puts $1                       # imprime o primeiro grupo
  end
end

Nota para amantes de Git: eu sei que eu podia ter feito isso usando git branch --show current, mas esse foi o primeiro exemplo que veio na minha cabeça para demonstrar o uso de regex…

Feature 6: threads fáceis

Se você quer trabalhar com várias threads, Ruby é talvez a linguagem mais fácil de fazer isso. Veja:

thread = Thread.new do
    puts "Estou dentro da thread!"
end

puts "Estou fora da thread!"

thread.join

Então, isso pode ser útil, por exemplo, para baixar vários arquivos ao mesmo tempo:

(1..10).map do |i|                       # itera de i=1 a i=10, inclusivamente
  Thread.new do
    `wget http://my_site.com/file_#{i}`  # você pode usar variáveis dentro de comandos!  
  end
end.each { |thread| thread.join }        # do/end e chaves servem para a mesma coisa

Feature 7: operações de arquivo e diretório embutidas

Em Ruby, todas as operações de arquivos são métodos da classe File e todas as operações de diretório são métodos da classe Dir, como deveriam ser. Em Python, por exemplo, se você quer ler um arquivo você usa open, mas se você quer apagá-lo você precisa usar os.remove, e os tem várias outras coisas que não são relacionadas a arquivos.

Então, em Ruby:

exists = File.exist? 'My File'           # métodos que retornam booleanos são terminados em ?
file_content = File.open('My File').read
File.delete 'My File'                     # parênteses são opcionais se não há ambiguidade

Conclusão

Espero que depois de ler este pequeno texto você considere usar Ruby como uma substituta para shell scripts complexos. Quero dizer, não espero que você deixe o Bash completamente, mas considere usar Ruby quando as coisas ficarem mais complexas. Claro que você poderia fazer isso tudo em Python, Perl, até JS, mas, como minha principal escolha eu acredito que Ruby é a escolha mais fácil e completa para isso!

Se você encontrou alguma coisa errada, ou se você tem alguma sugestão, por favor me diga aqui.

Update

Isto ficou em primeiro no Hacker News! Não apenas isso, mas começou discussões bem interessante nos comentários. Obrigado a todos!

Update #2

De alguma forma isto chegou no Matz, o criador de Ruby! E isso foi twitado por ele! Eu… não acredito!

Link: Ruby: a great language for shell scripts! - Lucas Seiki Oshiro : https://t.co/lestntomSR
https://t.co/lestntomSR

— Yukihiro Matz (@yukihiro_matz) June 25, 2024

Você provavelmente já o conhece, mas de qualquer forma, o operador unário (*) em Python (também conhecido como operador splat ) expande qualquer iterável (exemplos: listas, tuplas, conjuntos ou geradores) em argumentos posicionais de funções. Por exemplo:

def sum3(a, b, c):
    return a + b + c
    
my_list = [1, 2, 3]
sum3(*my_list) # = sum3(1, 2, 3) = 6
sum3(*range(3)) # = sum3(0, 1, 2) = 3

Também existe o operador **, ele expande mapeamentos (isto é, um objeto que mapeia uma chaves a valaores, como um dict, um orderedDict ou até um pandas.Series) em argumentos nomeados:

def sum3(a=0, b=0, c=0):
    return a + b + c
    
my_dict = {'a': 1, 'b': 2}
s = sum3(**my_dict) # = sum3(a=1, b=2) = 3, já que c usa o valor padrão (0)

Isso não parece muito útil? Bom, eles são mais do que você pensa! Aqui vou mostrar algumas construções legais usando * e **.

Objetivos

• Mostrar alguns truques usando * que podem ser úteis quando estamos lidando com listas, conjuntos, tuplas, dicionários e até strings;

• Comparar seu desempenho com outras construções funcionais ou imperativas, medindo o tempo, olhando o bytecode e o olhando código-fonte do CPython.

Não-objetivos

• Substituir numpy, pandas, polars ou qualquer outra biblioteca que implementa estruturas de dados eficientes e suas operações;

• Criar uma “boa prática”, “padrão de código”, dizer “faça isso porque é melhor”, etc. Encare com ceticismo tudo que você lê.

1: Converter entre para listas, tuplas e conjuntos

Eu mencionei sobre o * sendo usado como expansão de parâmetros em funções, mas ele também pode ser usado para expandir elementos na sintaxe de declaração de listas, tuplas e conjuntos, então, você pode usar ele facilmente para fazer conversões entre esses tipos:

# convertendo listas, tuplas e conjuntos
my_list = [1, 2, 3]
[*my_list]  # = [1, 2, 3]
{*my_list}  # = {1, 2, 3}
(*my_list,) # = (1, 2, 3), note a vírgula para garantir que é uma tupla!

Como isso se compara a usar um construtor?

Talvez você está pensando que você pode fazer a mesma coisa usando construtores de listas, tuplas e conjuntos, dessa forma:

# convertendo listas, tuplas e conjuntos
my_list = [1, 2, 3]
list(my_list)  # = [1, 2, 3]
set(my_list)   # = {1, 2, 3}
tuple(my_list) # = (1, 2, 3)

Sem problemas, use o que você preferir. Mas vamos analisar o que acontece debaixo dos panos e comparar as duas abordagens no caso das listas. Podemos conferir o bytecode usando o módulo dis:

from dis import dis

def f(x):
    _ = [*x]
    _ = list(x)

dis(f)

Este é o resultado (estou executando Python 3.12):

  2           2 BUILD_LIST               0
              4 LOAD_FAST                0 (x)
              6 LIST_EXTEND              1
              8 STORE_FAST               1 (_)

  3          10 LOAD_GLOBAL              1 (NULL + list)
             20 LOAD_FAST                0 (x)
             22 CALL                     1
             30 STORE_FAST               1 (_)
             32 RETURN_CONST             0 (None)

A primeira metade do bytecode se refere a [*x] e a segunda a list(x).

Na primeira metade ([*x]):

1. cria uma lista vazia (BUILD_LIST 0) e manda para o topo da pilha de execução;
2. carrega x no topo da pilha (LOAD_FAST 0);
3. estende a lista vazia (LIST_EXTEND 1) com o iterável x. Equivalente a list.extend(x);
4. guarda o resultado na variável _ (STORE_FAST 1).

Na segunda metade (list(x)):

1. carrega o construtor list na pilha (LOAD_GLOBAL 1);
2. carrega x na pilha (LOAD_FAST 0)
3. chama o construtor list passando xcomo argumento list(x) (CALL 1)
4. guarda o resultado na variável _ (STORE_FAST 1).

Nota: RETURN_CONST 0 faz a função devolver None, já que esse é o comportamento padrão em Python para funções que não têm valor de retorno

Então, a principal diferença entre elas é que a primeira cria uma lista vazia e depois a estende, enquanto que a segunda chama o construtor list. Qual é melhor? Vamos ver o código fonte do CPython!

• a implementação da instrução BUILD_LIST (aqui) chama a função _PyList_FromArraySteal(esta). Quando o tamanho da lista é 0, ela somente chama PyList_New. Ela é, basicamente alocação de memória;

• a implementação da instrução LIST_EXTEND (aqui) chama a função _PyListExtend (esta), que é só uma casca para list_extend, que vai estender a lista vazia com os valores de x;

• o inicializador de list (aqui) também vai chamar list_extend, estendendo a lista vazia recém criada com valores de x.

Dessa forma, ambas fazem a mesma coisa!

2: Criar listas a partir de geradores

Como eu disse antes, * pode expandir qualquer iterável, então, você pode usá-lo com qualquer gerador. Por exemplo, o clássico range:

[*range(5)] # = [0, 1, 2, 3, 4]

Mas você também pode usar ele com geradores mais interessantes. Eu recomendo fortemente que você leia sobre o módulo built-in itertools. Ele disponibiliza vários iteradores interessantes que você também pode usar aqui. Por exemplo:

from functools import permutations, pairwise

# Permutaç~oes
[*permutations([1, 2, 3])] # = [(1, 2, 3), (1, 3, 2), (2, 1, 3), (2, 3, 1), (3, 1, 2), (3, 2, 1)]

# Mapeia cada elemento com o seu próximo
[*pairwise([1, 2, 3, 4])]  # = [(1, 2), (2, 3), (3, 4)]

A mesma coisa pode ser feita para tuplas e conjuntos, da mesma forma que antes! E, da mesma forma que antes, a gente pode usar os construtores list, tuple e set no lugar da sintaxe correspondente (e eles vão fazer basicamente a mesma coisa debaixo dos panos, da mesma forma que o truque anterior).

3: Concatenar listas, tuplas e conjuntos

Como * pode ser usado em declaração de listas, você também pode usar para juntar uma ou mais delas:

list_1 = [1, 2, 3]
list_2 = [4, 5, 6]

[*list_1, *list_2] # = [1, 2, 3, 4, 5, 6]

Você ainda pode misturar listas (e outros iteráveis) e elementos soltos:

list_1 = [1, 2, 3]
list_2 = [4, 5, 6]

[*list_1, 11, *list_2, 12, 13, *range(3)] # = [1, 2, 3, 11, 4, 5, 6, 12, 13, 0, 1, 2]

Da mesma forma que os truques anteriores, isso pode usado para criar tuplas e conjuntos!

Olhando o bytecode de novo

Ok, mas o que acontece internamente? Vamos usar dis novamente aqui:

def f(a, b, c):
    _ = [*a, *b, *c]

dis(f)

E esse é o resultado:

  2           2 BUILD_LIST               0
              4 LOAD_FAST                0 (a)
              6 LIST_EXTEND              1
              8 LOAD_FAST                1 (b)
             10 LIST_EXTEND              1
             12 LOAD_FAST                2 (c)
             14 LIST_EXTEND              1
             16 STORE_FAST               3 (_)
             18 RETURN_CONST             0 (None)

Bem parecido com a saída do truque 1, mas aqui LOAD_FAST e LIST_EXTEND são chamados 3 vezes em vez de apenas 1 (como esperado, já que estamos concatenando 3 listas).

4: Concatenar dicionários

Da mesma forma, você pode concatenar dois ou mais dicionários, porém usando ** já que estamos lidando com mapeamentos em vez de um iterador:

d1 = {'I': 1, 'V': 5, 'X': 10}
d2 = {'L': 50, 'C': 100}

{**d1, **d2} # = {'I': 1, 'V': 5, 'X': 10, 'L': 50, 'C': 100}

Repare que você precisa usar ** aqui. Se você usar *, ele vai expandir apenas as chaves do dicionário, e então vai construir um conjunto em vez de um dicionário:

{*d1, *d2} # = {'C', 'I', 'L', 'V', 'X'}

Comentário sobre PEP 584

Essa construção era mais útil antes da PEP 584 em Python 3.9. Ela introduziu o operador de união (|) para dicionários da mesma forma como já havia para conjuntos. Hoje em dia você pode juntar dois dicionários da seguinte forma:

d1 | d2 # = {'I': 1, 'V': 5, 'X': 10, 'L': 50, 'C': 100}

Isso não significa que este truque se tornou inútil. Você pode usá-la para criar um novo dicionário a partir de outros dicionários e de novas chaves, por exemplo:

{**d1, **d2, 'D': 500, 'M': 1000} # = {'I': 1, 'V': 5, 'X': 10, 'L': 50, 'C':100, 'D': 500, 'M': 1000}

5: Tuple comprehensions

Em Python nós temos list comprehensions, dictionary comprehensions e set comprehensions. Mas não temos tuple comprehensions:

[2 * x for x in range(10)]     # list comprehension
{2 * x for x in range(10)}     # set comprehension
{x: 2 * x for x in range(10)}  # dict comprehension
(2 * x for x in range(10))     # tuple comp... não, é um gerador!

Mas a gente meio que pode ter uma “tuple comprhension” convertendo um gerador para uma tupla usando o truque 2:

(*(2 * x for x in range(10)),) # "tuple comprehension"

Note: se isso parece útil para você, então talvez tuplas não seja o que você está precisando! Tuplas são mais do que listas imutáveis: tipicamente, você usa tuplas quando cada posição tem um significado, como em um par ordenado. Como sugestão, leia a seção “Tuplas não são apenas listas imutáveis” no livro Python Fluente de Luciano Ramalho.

6: Imprimir listas de forma bonita

Às vezes você quer imprimir uma lista, mas em uma forma mais legível para humano do que a representação [foo, bar]. Você pode, por exemplo, usar str.join:

my_list = [1, 2, 3]
print(' -> '.join([str(x) for x in my_list])) # 1 -> 2 -> 3

Mas existe uma solução ainda mais limpa: você pode usar * para passar cada elemento da lista como um parâmetro. Depois você pode especificar qual separador você quer usar (por padrão, espaço):

print(*my_list)             # 1 2 3
print(*my_list, sep=' -> ') # 1 -> 2 -> 3

Muito mais limpo. Outro exemplo, um código simples para gerar um arquivo CSV em apenas 3 linhas:

data = [
    (1, 2, 3),
    (4, 5, 6),
    (7, 8, 9)
]

with open('output.csv', 'w') as f:
    for row in data:
        print(*row, sep=',', file=f)

7: Transpor matrizes

A função zip itera simultaneamente sobre dois iteradores, por exemplo:

for pair in zip(range(3), range(3, 6)):
    print(pair)   # (0, 3) (1, 4) (2, 5)

Dessa forma, você pode usar * para iterar sobre elementos de todas as linhas ao mesmo tempo usando zip, ou em outras palavras, iterar sobre as colunas:

my_matrix = [
    (1, 2, 3),
    (4, 5, 6),
    (7, 8, 9)
]

for column in zip(*my_matrix):
    print(column)   # (1, 4, 7) (2, 5, 8) (3, 6, 9)

Se você criar uma lista de colunas, então você terá uma matriz transposta! Você só precisa converter zip(*my_matrix) para uma lista usando a mesma sintaxe de antes:

[*zip(*my_matrix)] # [(1, 4, 7), (2, 5, 8), (3, 6, 9)]

E o NumPy?

O NumPy é incrível, é claro! Você pode transpor uma matriz usando my_matrix.T, e isso é O(1). Mas você precisará:

1. importar NumPy
2. usar numpy.array ou similar

Se você já está usando o NumPy e você precisa transpor uma matriz, vá em frente, use .T. Mas se você vai usar NumPy apenas para transpor uma matriz, talvez ele não seja a melhor opção. Importar o NumPy e converter uma matriz de listas do Python para NumPy custa tempo.

Aqui vai um teste simples (tente rodá-lo em sua máquina)

from time import time

a = time(); import numpy as np; b = time()
print('Numpy loading time: ', b - a)

my_matrix = [[i * 10 + j for j in range(10)] for i in range(10)]

a = time(); transposed = [*zip(*my_matrix)]; b = time()
print('zip time: ', b - a)

a = time(); transposed = np.array(my_matrix).T; b = time()
print('numpy time: ', b - a)

Na minha máquina (um velho i5 de segunda geração), essa é a saída:

Numpy loading time:  0.10406970977783203
zip time:  7.62939453125e-06
numpy time:  1.6450881958007812e-05

Repare que ele tomou 2x mais tempo para criar um np.array a partir de uma matriz existente e o transpor, e tomou mais de 10000x o tempo para importar o NumPy! E essa é uma matriz relativamente grande (10x10)!

“Não use um canhão para matar um mosquito” - Confúcio

8: Selecionar elementos sem repetição

Uma das diferenças entre listas e conjuntos é que conjuntos não podem conter o mesmo elemento duas vezes. Então, se nós queremos uma lista com elementos únicos, nós podemos convertê-la para um conjunto e convertê-la de volta para uma lista:

list = [1, 1, 2, 3, 5]
[*{*list}] # [1, 2, 3, 5]

Note que conjuntos não têm ordem. Mas você pode usar um collections.Counter aqui e ele irá preservar a primeira ocorrência (caso precise):

from collections import Counter

[*Counter(list)] # [1, 2, 3, 5]

# or

Counter(list).elements()

Da mesma forma que antes, você poderia usar numpy.unique, mas lembre-se de Confúcio!

9: Criar uma lista com substitutos para elementos nulos

Olhe esta lista com dados sobre super-herois (seus nomes, seus nomes reais e seus poderes):

heroes = [
    {
        'name': 'spider-man',
        'real name': 'peter parker',
        'powers': ['wall crawling', 'webbing'],
    },
    
    {
        'name': 'batman',
        'real name': 'bruce wayne',
        'powers': []
    }
]

Se você quer criar uma representação legível para humanos de cada um desses herois, você poderia, por exemplo, fazer isso:

def hero_string(hero):
    s = ''
    s += f'name: {hero['name']}\n'
    s += f'real name: {hero['real name']}\n'

    if hero['powers']:
        for power in hero['powers']:
            s += f'power: {power}\n'
    else:
        s += 'No powers!'
    return s

Repare que para o Spider-Man ele vai mostrar seus poderes e para o Batman ele vai mostrar “No powers!”.

Ok, mas somar strings não é tão eficiente quanto escrever str.join. Uma segunda solução seria:

def hero_string(hero):
    names = '\n'.join([
        f'name: {hero["name"]}',
        f'real name: {hero["real name"]}'
    ])

    if hero['powers']:
        powers = '\n'.join(f'power: {power}' for power in hero['powers'])
    else:
        powers = 'No powers!'

    return '\n'.join([names, powers])

Bem, nós não conseguimos escrever com só um '\n'.join já que precisamos tratar o caso especial do Batman… Mas nosso amigo * pode nos ajudar aqui:

def hero_string(hero):
    powers = [f'power: {power}' for power in hero['powers']] or ['No powers!']

    return '\n'.join([
        f'name: {hero["name"]}',
        f'real name: {hero["real name"]}',
        *powers
    ])

Dessa forma, powers vai ser uma lista de linhas contendo os poderes ou contendo “No Powers!” caso o heroi não tenha poderes. Então, ela será expandida depois com join.

10: Conferir se todos os elementos estão em um conjunto

Este é meu preferido. Se você quer conferir se todos os elementos de uma lista estão contidos em outra lista, você pode fazer isso (quando os operandos são conjuntos, o operador <= significa “é um subconjunto de”):

a = [11, 22, 33]
b = [11, 22, -1]
c = [11]
d = [11, 22, 33, 44]

{*a} <= {*d} # true
{*b} <= {*d} # false
{*c} <= {*d} # false

Você também pode usar == para conferir se os elementos de duas são os mesmos (mesmo que sua ordem seja diferente ou que eles tenham elementos repetidos):

{*a} == {*d}

Você também pode usar isso com strings. Este exemplo checa se uma string contém apenas vogais:

{*my_string} <= {*'aeiou'}

Complexidade

Uma abordagem mais imperativa sobre isso seria:

result = True

for x in a:               # O(len(a))
   if x not in d:         # O(len(d))
       result = False
       break

A operação in sobre listas é O(n), então, essa abordagem imperativa é O(len(a) * len(d)) no pior caso e O(len(d)) no melhor caso.

De volta à nossa solução anterior, a criação de um conjunto é O(n) e a operaçao set1 <= set2 é O(len(set1)), então, nossa solução é O(len(a) + len(b)) no pior caso. Muito melhor, sem dúvida. Mas no melhor caso ela também vai ser O(len(a) + len(b)), já que ela precisa iterar sobre todos os elementos de a e d mesmo que essas listas sejam completamente diferentes! Então, a gente pode melhorar nossa solução, pelo menos em termos de complexidade.

A nossa solução resolve isso, mas claro que ela não é tão elegante:

set_d = {*d}
all(x in set_d for x in a) # devolverá False na primeira divergência!

Então, essa solução é O(len(d)) no melhor caso (o primeiro elemento de a não está em d) e ainda será O(len(a) + len(d)) no pior caso (todos os elementos de a estão em d). Mas para listas pequenas (ou strings, tuplas, etc) esse tipo de problema não é muito relevante.

Conclusão

Eu espero que você tenha gostado deste texto! Se você conhece algum outro truque legal usando * ou **, se você encontrou alguma coisa errada, ou se você tem alguma sugestão, por favor me diga aqui.

Leitura complementar

• Documentação do disassembler do Python
• Python Fluente, de Luciano Ramalho
• Complexidade de tempo em Python

Intro

It says “19 minute read”.

If you’re thinking “it’s easy, I’ll keep squashing so I can save those 19 minutes of my life”, well, I must say that it is not an excuse, you can stop squashing right now without reading this. But if you still thinking that using squash merging is a good idea, please, keep reading this. You’ll probably won’t want to squash your anymore after reading this, except in some very specific cases (and those cases probably are not what you’re expecting).

This is long and dense, so, no more intro. Here we go!

Goals

• Explain what squash merges actually are, detailing how Git works under the hood;
• Show how the most well-known “pros” about squash merging are conceptually wrong;
• Show situations that squash merges can be harmful;
• Show what you can (and should) do instead of using squash merge;

Non-goals

• Tell something that works for me and dictating that it will also work for you;
• Create another “good practice guide” for people follow without questioning if is true. Be skeptical;

Why do you use squash merge?

If you consider that squash merge is a good practice, have you ever thought why it is a good practice? Or are you only repeating something that you have heard?

Be honest.

In the past, I also thought it was cool, but as I studied Git a little deeper soon I figured out that it doesn’t make sense. Not only that, but it is never mentioned as good practice in Git documentation, not even as a practice:

• Pro Git (the official Git book) has two chapters and a appendix about merge and it barely mentions squash in the merge context (it only mentions here and here, using squash only as an intermediate tool);

• Apart from git merge manpage and Pro Git, the official Git documentation only mentions squash in gitfaq, focusing on the problems of doing that;

• Last but not least, Git itself doesn’t have a single “squash and merge” command, you have to run two commands to perform it (we’ll discuss about that later).

So, before we go deeper, I need you to ask you two things:

First, what do you think that a squash merge is?

(go ahead, write it, it’s only a textarea without any hidden JavaScript)

Second, why do you think you should do it, given the first answer?

Ok, thanks! We’ll come here later. Now, before I tell you why you shouldn’t squash your commits (and before you squash your commits again), we need to have it clear what a squash actually is. And I must say most people who squash do it because they don’t know what a squash merge is. And, again, I must say this is because they have two major misconceptions about Git.

There’s where we start.

The first misconception: what a commit stores

I strongly recommend you that you read Pro Git, the official Git book. For our purposes here, section 1.3 and chapter 10 will be enough. But by now what we need to know from it is that Git commits don’t store changes. They store snapshots.

Repeat after me: “Git commits don’t store changes, they store snapshots”.

And that’s the first misconception. When we’re using commands such as git show, git diff or external tools such as the Pull Request UI on GitHub we think that commits are sets of changes of states. But no, each commit is a state plus some metadata.

Under the hood, Git stores the repository data in the so-called objects. Each object stores data and is identified by its SHA-1 hash. Roughly saying, we have three main types of objects:

• Blob: contains file contents;
• Tree: represents a directory. It is a list of files or directories, the hash of their contents (a blob if it is a file or a tree if it is a directory) and their file permissions;
• Commit: contains the author, the commiter, its timestamp , its message, its parents and the snapshot

It is important to say that the child commit points to its parent or parents, but the parent commit doesn’t point to its children. The first commit doesn’t have any parent, and a merge commit has two parents or more. In the case of merge commits, the parent order matters.

The snapshot of a commit is just the tree object that represents the root directory of the commit when it was created.

Perhaps you are thinking: “that is not possible, that would be a waste of disk space”. But that it is not true: a file that hasn’t changed between two commits has the same content in both states, so their contents are stored in the same blob. This is also true for directories.

And if you’re thinking “this is not true, I saw something about deltas, those are the commit changes”, yeah, those deltas are changes but they are not changes between commits. They are related to a compresion that Git does using something called packfile, but you don’t need to know about them by now. Only keep in mind that Git somehow compresses the objects, so the disk space is not something you should care too much.

Just one more thing: branches ares not objects. They are references, that is, only pointers to commits. This is, there’s no such thing as “a commit is in a branch”, as a branch is not a set of commits as we may think. But it is very common to say that, even though it is not 100% correct. It is just a shorter way to say “the commit is an ancestor of the commit pointed by the branch”.

For now on, sometimes I’ll refer to a commit pointed by a branch as just “a branch”.

I disccussed a little more about objects here, but again, I strongly suggest you to read about that on Pro Git for more datailed info.

How merge works

Now that we know what a commit and a branch are, we can proceed to see how merge works.

In Git, by “merge” we can think as three things, at least:

1. The command git merge
2. A merge commit (i.e. a commit with two or more parents)
3. The mechanism used by git merge to join the contents of both branches

When you run git merge <another branch>, you tell Git to join the contents of both branches and create a merge commit. The merge commit will have as the first parent the one pointed by the current HEAD and the commit pointed by the merged branch as its second parent.

When the commit of the current branch is a direct ancestor of the commit of the merged branch, Git will perform a fast-forward. Fast forwards don’t create merge commits, they only make the current branch point to the same commit as the merged branch, so they are not true merges. You can change this behaviour by using --no-ff. GitHub also provides a feature for merging PRs without fast-forwarding them in those cases. Personally, I don’t like fast-forwards, so I use no fast forward when possible.

So, by now we know what is 1 (git merge) and 2 (merge commit), but what about 3? What is the mechanism that Git uses to join the files of both branches? Well, Git performs an algorithm called three-way merge that uses the snapshots of three commits in order to figure out what should be kept in the merge commit and what should not:

• the commit pointed by the current branch (named A);
• the commit pointed by the branch that we want to merged (named B);
• the commit that is the last common ancestor between A and B (named O).

When performing a three-way merge, Git will keep everything that are the same in A and B. If there’s something different, it will compare O and A, and O and B. If something doesn’t changed from O to A but changed from O to B, it keeps the change introduced in B, and vice-versa. If O, A and B differ, then we have a conflict and you need to manually fix it.

This picture shows how the three-way merge works. Different colors means different contents of a file:

Note: for plaintext files, if there’s a conflict Git will perform three-way merge comparing the lines, so it can merge the contents of a file that don’t overlap. If there’s a overlap, then it puts the conflict marks.

This mechanism is also used in other commands, such as cherry-pick, revert, rebase and stash, but this is a topic for another post.

This is really brief explanation about merge and there’s a lot to talk about (e.g. how Git handles renames, file permissions, submodules and so on). Here I discussed a little more about merge, but by now this is enough.

As an exercise: try to imagine how hard and expensive merge would be if Git stored changes instead of snapshots.

What squash merge actually is

By now, we know what is a merge. But how about a squash merge? I just googled “why squash merge?” and I found these definitions about what it is:

• “Instead of each commit on the topic branch being added to the history of the default branch, a squash merge adds all the file changes to a single new commit on the default branch”

• “It turns all your changes into one single commit and then adds that to the main branch”

• “By squashing commits, developers can condense a series of small, incremental changes into a single meaningful change”

• “Squashing retains the changes but discards all the individual commits”

Well, time to revisit your answer. Click here to see it. Is your answer similar to those? Well, I ask you that because there’s something that all those answers have in common: they are all wrong!

And they are wrong because, remember: Git commits don’t store changes, they store snapshots.

Again: Git commits don’t store changes, they store snapshots.

Now, an exercise: try to rewrite those answers (or your answer, if it has the same idea) replacing the wrong idea of commits storing changes by the correct idea of commits storing snapshots. Here’s another textarea only for your convenience:

Was it hard? Well, this is because that idea of what a squash merge is is based on a wrong idea of what Git is, and it doesn’t make any sense in real life.

I bet that if you regularly squash merge you do it by using the UI of GitHub or similar, and you never did it locally on your machine through CLI, using this button:

And I say that because, as I said before, there’s no command for squash merging in Git! In fact, in order to do the same thing as the “squash and merge” button on GitHub you’ll need two commands:

git merge --squash another_branch
git commit

Several useful Git commands that are a single command originally were a set of commands, such as git stash, git subtree and so on, but this never managed (at least so far) to be a single command. That should raise an alert on you that something is out of place here.

Let’s check what happens when we perform a squash merge locally:

• The first command is the squash itself. It merges the current branch with the other one, but it doesn’t create a merge commit. Instead, it only merges the files (using the mechanism that we discussed before) in the filesystem (in Git jargon, working directory) and stages them just like git add does (in Git jargon, it adds them to the index);

• The second command is just a standard git commit. When we perform a git commit we create a new commit after the state of the index (the staging area), that contains the merged files and the untouched ones. The previous step creates a commit message containing a list of the messages of the branch that was squashed, and it is used as template here.

A commit whose contents are a merge of the two merged branches. Hmmmm, sounds familiar? Isn’t it a merge commit?

Oh wait, isn’t it a merge commit????

Are squash merge and standard merge the same??

WHAT???

Please, calm down. They are different. How? Remember that a merge commit has two or more parents? That’s the difference. This commit has only one parent: the commit pointed by the current branch before merging. This way, there’s no reference to the other branch, and that’s the only difference between the squash merge commit and the true merge commit.

Don’t you believe? What more could change?

• The author, commiter, timestamps or message? These are only metadata;
• The snapshot? No, it is the same, as it was generated by the same mechanism.

The only thing left is the parents. Squash merge is the same as the true merge but with a missing information: the reference to the merged branch.

Why is it good?

Is it good?

This leads to the second misconception.

The second misconception: the fallacy of the clean history

I don’t know if you still think that squash is a good idea after knowing what it really is. But anyway, let’s read again why you think that squash merges are good: click here.

Just like I did before, here are some answers from some of the first results after a quick Google search for “why squash merge”:

• “Squash merging keeps your default branch histories clean”
• “Your base branch remains clean”
• “This helps developers to maintain a clean Git commit history”
• “This [squash merging] helps keep your code history clean”

See? It is very common to say that squash merges keeps the history clean. And, was we saw, the only difference between the squash merges and true merges is that squash merges don’t preserve the reference to the original branch, so “clean” in this situation means “less information” and “less commits”. And I ask you: why a commit history with fewer commits are the better? Here’s another textar… (no, enough textareas!)

If it was true, the best commit history would be not commiting at all. So, the best way to use Git would be not using Git. Something is wrong here.

That is our second misconception. Cleaner commit histories are better, indeed, but a history with fewer commits is not cleaner. So, what is a good commit history?

A good commit history

A good commit history is a history that contains good commits.

Personally, I’m intrigued that it is a common sense that most developers agree that code quality and data quality are important while it is harder to find someone that really cares about the code repository quality. And the repository is the database where we store code.

Lets recap some practices that we commonly associate with code quality:

• Code that is easy to understand;
• Code that implements simple solutions;
• Code that is easy to debug, when needed;
• Code that is simple;
• Code that can be tested;
• Code that follow the same codestyle;
• Good documentation.

And about data quality:

• Data that is easy to retrieve;
• Data that is accurate;
• Data that is clean.

I don’t want to write a commit guideline here, but there is a lot of good resources that you can read about. I’ll leave some of them at the bottom of this page. I don’t think that you should follow them as a religion (I think that you should follow them as long as them make sense), but there are some practices that worth be mentioned here:

1. Atomic changes: each commit should introduce an indivisible codeset;
2. Write good commit messages: use the commit message to describe the change you introduced;
3. Don’t commit incomplete work: if it is not ready, then don’t commit (use the staging area);

And we if we do that, we’ll have more commits, but they will be good commits. They will be meaningful and they will be easier to debug with tools such as the ones that I mentioned here. Not only that, it will be easier to cherry-pick and revert specific changes.

There are some commit guidelines, I don’t think that you need to adopt any specific one, but you can take a look a decide if they make sense to you. Or they can be a inspiration for you create your own:

• the Linux kernel, that is the project that Git was created for has a strict guideline for writing patches (commits that are sent by email). I also had a patch that was rejected by doing too much, and I need to rewrite my history and send again.

• the conventional commits specification is less strict then the Linux kernel, as several projects follow them;

• Gitmoji is similar to conventional commits, but it uses emoji to identify the commit types (for good or for bad).

For example, Marlin, a firmware for 3D printers, uses Gitmoji. Look how it is easy to find commits with bugfixes:

Last but not least: don’t fear rewriting history. Of course it can be dangerous, but you can use it in your favor to create a clean commit history. I suggest you to read this. I also suggest you to include commit history reviewing to your code reviewing process, just like the Linux kernel does (and rejecting bad commit histories like they did with me!).

When squash can be evil

I think I have enough evidence for you to see that squash is not exactly something good and the arguments to use it are based on wrong principles of what Git is and what are a so called clean history. But if you asking if there’s a case where squash merges can break something, I once saw it silently breaking a repository with submodules as a consequence of not having the reference of the merged branch.

At first I started to write about that situation but I thought it will make this article even longer than it already is, so I wrote another article only about it here.

So, what should I do?

If you are used to perform squash merges probably you are thinking “what should I do?”, because it still feels comfortable to keep squashing even though you they are not the best choice. Let’s do the right things from now on.

But squashing makes my life so easy…

Let’s imagine you are driving a car with manual transmission. You have 5 forward gears and one reverse. Do you think it is a good idea to drive your car backwards because you don’t want to shift gears? I hope you don’t, and I hope that you at least suspect that the car have 5 gears instead of 1 because things are not so easy and pretending they are easy is not the solution (err… unless you drive an automatic).

And here it is the same. We need to understand our tools and how to use them.

Some people say: “if you squash you have a linear history, only seeing the merge commits”. Ok, but you can see it without squashing (and without losing the original commits) by running:

git log --first-parent

“Squash merges are easy to revert”:

git revert -m 1 <commit>

“Squash merges are easy to cherry-pick”:

git cherry-pick -m 1 <commit>

“Squash merges are easy to <insert something>”: read the documentation about how to do something properly! No excuses!

If you are convinced…

Here are some things that you can do:

• Try to write meaningful commits like we discussed before. It is hard at first, but it will soon become easy and it will pay your effort;

• On you code reviews, also review the commit history. Check if it is clean and, if it is not, ask to the author of the code to rewrite the history, just like you would do with code;

• If you are a junior developer, listen to the seniors developers but don’t take everything that they say as true. Question everything, and that will make you grow;

• If you are a senior, don’t tell juniors to do something that you aren’t certain that is right and that you believe that it is right because another senior told you to do that when you were a junior. Don’t be a parrot;

• The same applies here. Question everything that I said. Don’t do anything only because I told here.

If you are not convinced…

I tried to do my best.

Is there any good use case for squash merge?

Oh yeah, of course. It is a tool just like many others that Git has, so of course it can be useful! But there are a lot of more useful Git tools that people generally don’t know, for example, some searching and debugging tools that I explained here.

I stopped to think for about two minutes in a use case for squash. And here it is one: supposing that you have an old branch with only one commit diverging from your main. Now you want to merge it, but the main branch changed so much that the code would need to be compatible with those changes.

An option here is to rebase foo onto main, make the code compatible with the new main, and then git commit --amend. Other is to cherry-pick foo (in practice, it would be the same as rebasing). But you can also do this:

git checkout main
git checkout -b bar
git merge --squash foo

# edit the code in order to make it compatible

git commit

In that situation, we’re using git merge --squash to apply the changes introduced in foo to our files, without commiting. Then we make the code compatible and create a new commit.

And that’s it. A simple tool that may be useful in very specific situations.

Conclusion

Thanks for your time! I hope that this may be useful. If something is wrong, please open a issue.

And for the last time, remember: Git commits don’t store changes, they store snapshots!

Further reading

The references that I mentioned in this text are listed here.

For general Git information:

• Pro Git by Scott Chacon: It’s the official Git Book. I’ll select the sections that are most important here.

About Git internals:

• Pro Git - What is Git: explains what Git is and compares it with delta-based versioning systems;
• Pro Git - Git Internals: explains how Git works under the hood.

About merge:

• Wikipedia - Merge (version control): explains merge and three way merge

About commiting:

• How to Write a Git Commit Message by cbeams: Advices about what to put in a commit message;
• Git 101 by Matheus Tavares: it’s a general presentation about Git but it focus on commits after slide 29;
• Pro Git - commit guidelines: chapter of Pro Git about how to commit;
• Philosophy of Linux kernel patches: about patches (commits) in the Linux Kernel;
• Conventional Commits v1.0.0: a convention about commits that is adopted by several projects;
• Gitmoji: similar to conventional commits, but using emoji.

About rewriting history:

• Git: Rewriting History 101 by Matheus Tavares: about when, how and why rewrite the commit history;
• Pro Git - rewriting history: Chapter of Pro Git about rewriting history.

About squash merging (note that both discuss about the fallacy of the clean history):

• Squash commits considered harmful by Manuel Odendahl. After writing some sections here I found this article that is quite similar;
• Squash merges are evil by L. Holanda. Another good article against squash merge.

Other articles about Git that I wrote:

• Git as debugging tool;
• Git: merge with submodules;
• Git: the danger of squash merging submodules.

Para aqueles que não conhecem, o OpenSCAD é um programa e uma linguagem de programação para a modelagem de objetos 3D, principalmente para impressão 3D. Sendo uma linguagem de programação, ele pode ser muito produtivo para modelagem, já que ele é completamente parametrizável e tem várias bibliotecas.

Esse curso foi um desafio pessoal, já que:

• foi o primeiro curso que preparei e lecionei;
• provavelmente é o primeiro curso de OpenSCAD em português;
• o público era incrivelmente diverso, já que era composto por aproximadamente 50 pessoas de diferentes áreas profissionais (desenvolvedores de software, professores de matemática, engenheiros e até dentistas!), algumas pessoas sabiam muito sobre programação e outros mal sabiam o que eram isso e a maioria nunca usou uma impressora 3D!

Esses são os slides de cada aula:

1. Aula 1: Introdução ao OpenSCAD, instalação, comparação com outras ferramentas;
2. Aula 2: Intrdoução à linguagem de programação do OpenSCAD, focando em aspectos de programação como tipos de dados, funções, operadores e por aí vai;
3. Aula 3: Objetos 3D primitivos e operações sobre eles;
4. Aula 4: Controle de fluxo e reuso de código, com módulos e bibliotecas;
5. Aula 5: Extrusão de 2D para 3D, importação de arquivos STL e SVG;
6. Aula 6: Boas práticas de programação, linha de comando, integração com Python, impressão 3D.

Esses slides são apenas uma referência. O curso em si foi mais do que isso. Toda aula demonstrei tudo que está contido nesses lides, programei/modelei ao vivo e mostrei passo a passo o raciocínio de como modelar. Além disso, também tinha tarefas para os alunos fazerem após cada aula e que não estão aqui.

• Os Macs Intel podiam fazer dual-boot de macOS e Linux (e até mesmo Windows!). Os Mac Apple Silicon não conseguem;
• Ok, isso não é totalmente verdade porque a equipe do Asahi Linux têm trabalhado pesado para conseguir rodar o Linux nativamente no Apple Silicon. Porém, apesar do incrível progresso deles, ele ainda não está 100%, e é um Linux ARM;
• O VirtualBox para o Apple Silicon praticamente não existe até agora (quer dizer, tem um beta que não fazia quase nada e que desapareceu da página de downloads);
• O Parallels existe, mas você precisa pagar pra usar;
• Tem o QEMU. Não me entenda mal, o QEMU é excelente, mas ele pode ser bem chato de configurar e executar através da linha de comando (em comparação ao VirtualBox, por exemplo);
• Ainda existe o UTM, um front-end para o QEMU, mas ele não roda máquinas x86-64 e não é tão fácil instalar uma distro ARM nele.

Mas pera aí, não jogue fora seu belo Mac, ainda tem mais uma opção para você: o Lima. Ele é um wrapper para o QEMU que permite que você crie facilmente máquinas virtuais Linux ARM e x86-64.

Mas ele tem algumas desvantagens:

• É uma ferramenta de linha de comando, não tem uma interface gráfica;
• Você até pode rodar alguns apps com interface gráfica, mas a experiência não é das melhores;
• A interoperabilidade com o macOS é meio fraca.

Neste tutorial vou te mostrar como configurar uma instância de Linux x86-64 no Lima, e como usar ela em seu ambiente de desenvolvimento. Note que você precisará rodar comandos no Mac hospedeiro e no Linux convidado, então eu vou representar seus prompts como mac$ e linux$ para deixar claro onde que você deve rodar cada comando.

Instalando o Homebrew

Se você já tem o Homebrew instalado, você pode pular esta seção. Mas se você não o tem, eu recomendo fortemente que você o instale, já que ele é um gerenciador e instalador de pacotes para o Mac, assim como o apt-get/dpkg é para o Debian/Ubuntu/Mint e o pacman é para o Arch/Manjaro.

Você pode instalar o homebrew executando em seu terminal:

mac$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh")

Tome cuidado!

Não copie e cole nada em seu terminal a não ser que você confie na pessoa que disse para você fazer isso!

Se você não confia em mim então copie direto de https://brew.sh/ !

Instalando o Lima

Ok, tendo o Homebrew instalado, execute:

mac$ brew install lima

Você pode ver se a instalação deu certo executando:

mac$ limactl --version

Visão geral do Lima

Como eu disse antes, o Lima usa o QEMU por debaixo dos panos, e ele gerencia máquinas virtuais (também chamadas de instâncias aqui). limactl é o comando que você usa para interagir com o Lima. Aqui estão alguns subcomandos do limactl (você pode ver mais deles rodando limactl --help):

• limactl list: lista VMs;
• limactl create: cria uma VM;
• limactl shell: executa um shell em uma VM;
• limactl start: inicia uma VM;
• limactl stop: encerra uma VM.

Se você executar limactl list você não vai ver nada por enquanto. Isso é porque você não tem nenhuma instância, então você vai precisar criar uma com limactl create.

Depois de criar uma, você deverá inciá-la com limactl start. Se você não precisa mais ter ela em execução, você pode pará-la com limactl stop (instâncias do Lima podem desperdiçar sua bateria…). Depois de iniciada, você pode executar limactl shell e isso vai iniciar um shell (provavelmente Bash) em sua VM.

Note que apenas encerrar o shell não encerra a instância. Note também que essas são VMs com armazenamento persistente, você não irá perder seus arquivos e configurações depois de encerrá-las.

Criando uma instância x86-64

Por padrão, se você executar limactl create em um Apple Silicon, o Lima vai criar uma instância ARM. Então, você precisa especificar que você quer uma instância x86-64 com --arch=x86-64:

mac$ limactl create --arch=x86_64 template://debian

Como você deve suspeitar, estamos criando uma máquina virtual Debian, mas você pode escolher qualquer distro que você quiser (se suportar x86-64) se ela estiver nesta lista. Apenas se assegure que existe uma imagem x86-64 para ela! E você pode ter tanto instancias x86-64 quanto ARM!

Agora execute:

mac$ limactl list

Se tudo estiver ok você deverá ver sua nova instância debian aqui!

Configurando o SSH para a sua instância

Como eu tinha dito antes, a interoperabilidade entre o hospedeiro Mac e as instâncias do Lima é… estranha. O lima pode ler os arquivos do Mac mas não pode escrever neles. Os hosts Mac não podem ler nem escrever instâncias do Lima (ok, tem uma exceção para isso mas ela não é recomendada).

Mas nós podemos configurar o SSH para ter uma interoperabilidade aqui. Execute:

mac$ limactl edit debian

Ele vai abrir um editor de texto (aquele que estiver configurado na variável de ambiente EDITOR, você pode trocá-lo pelo seu favorito como vim, emacs, code e por aí vai antes de executar isso).

Adicione isso ao fim do arquivo:

ssh:
  localPort: 2022

Isso vai configurar a porta SSH padrão. Você pode configurar a porta SSH para a que você quiser.

Adicionando a VM como um host SSH no .ssh/ssh_config

Isso só é necessário se você está usando Visual Studio Code, mas eu recomendo fazer isso de qualquer jeito.

Adicione em seu ~/.config/ssh_config as seguintes linhas:

Host lima-debian
  HostName localhost
  Port 2022

Isso vai identificar a VM para o SSH como lima-debian. Mude a porta para aquela que você escolheu no passo anterior.

Executando sua instância

Ok, vamos executar sua instância x86-64 pela primeira vez. Execute:

mac$ limactl start debian

Como essa é a primeira vez, isso pode levar alguns minutos para terminar. Se tudo foi ok, execute:

mac$ limactl shell debian

Isso vai abrir um shell (neste caso, o Bash) na sua instância. Se você não acredita que esse é um Linux x86-64, você pode ver isso assim:

linux$ uname -a

Terminando a configuração do SSH

O SSH vai permitir você acessar arquivos tanto do Linux convidado quanto do Mac hospedeiro. Para isso, você precisará de uma chave SSH configurada no seu Mac. Se você não tem, siga estas instruções para gerar uma.

Dica:

Considere usar o Secretive. Ele é um app open-source para o Mac que guarda a chave privada SSH no Secure Enclave, então ninguém (nem mesmo você) tem acesso a ela. Ela é protegida pelo sua senha de usuário ou Touch ID.

Mas claro, você consegue ver sua chave pública!

Copie a chave SSH armazenada em ~/.ssh/id_rsa.pub no seu Mac. De volta à VM, cole ela no fim do ~/.ssh/authorized_keys. Isso autoriza o seu Mac para acessar os arquivos da sua máquina virtual Linux através do SSH.

Acessando usando seu editor de texto

Visual Studio Code

Se você usa o Visual Studio Code, instale a extensão Remote - SSH.

Depois de instalá-la, você verá na sua esquerda um novo ícone, chamado “Remote Explorer”. Clique nele, e você verá o lima-debian como um remote. Passe o seu mouse por cima, e vai aparecer uma seta. Clique nela, e ele irá se conectar à sua VM.

Agora, você pode usar o VSCode com os arquivos dentro da VM da mesma forma como você usaria se estivesse trabalhando com ele no hospedeiro.

Emacs

Voc~e pode se conectar usando o TRAMP: use o atalho C-x C-f da mesma forma que você faria pra abrir um arquivo local, mas use isto como caminho:

/ssh:localhost#2022:<path>

Se você está usando outra porta que não seja a 2022, então substitua ela. Substitua também <path> pelo caminho do arquivo na VM que você quer abrir.

Se você adicionou lima-debian para sua configuração do SSH, então você pode usar como caminho:

/ssh:lima-debian:<path>

Vim

Apenas use o Vim dentro da sua VM :-)

Outros editores / IDEs

Se você está usando outros editores ou IDEs, você terá que procurar como o desenvolvimento remoto funciona nele, e configurá-lo para usar o SSH com localhost como host e 2022 como porta (ou a porta que você escolheu).

Copiando arquivos

Agora que você já tem o SSH, você pode usar scp para mover arquivos do hospedeiro para o convidado e vice-versa. Ele funciona como o cp mas ele pode copiar arquivos entre computadores (neste caso, um físico e uma máquina virtual).

Do hospedeiro para o convidado:

# troque 2022 pela porta que você escolheu
mac$ -P 2022 scp my_file localhost:destination

# ou, se você adicionou a instancia ao .ssh/ssh_config:
mac$ scp my_file lima-debian:destination

E do convidado para o hospedeiro:

# troque 2022 pela porta que você escolheu
mac$ scp -P 2022 localhost:my_file destination

# ou, se você adicionou a instancia ao .ssh/ssh_config:
mac$ scp lima-debian:my_file destination

Montando a VM do Lima no seu sistema de arquivos

Também é possível montar o Lima como um drive através do SSH de forma que você consegue de forma simples abrir arquivos da VM como se eles estivessem localizados na sua máquina hospedeira. Isso é possível com o SSHFS.

Mas tenha cuidado! Isso é baseado no MacFUSE, um port do FUSE para Mac. O FUSE é uma forma interessante de criar sistemas de arquivos falsos no Linux, mas o Mac não o suporta por padrão. Então, o MacFUSE é um kext (uma extensão de kernel) que habilita o FUSE no kernel do Mac. Para instalar você precisa desinstalar algumas proteções no Mac, então, siga com cuidado.

Você pode encontrar mais informação sobre como instalar e configurar o MacFUSE e o SSHFS aqui.

Uma vez instalado, crie um diretório vazio em algum lugar no seu sistema de arquivos do seu Mac (estou usando~/sshfs/lima). Seguindo a configuração de SSH que temos até agora, você pode montar a raiz do Lima no seu sistema de arquivos rodando:

mac$ sshfs lima-debian:/ <o diretório que você criou>

Leva alguns segundos para montar.

Você pode ler mais sobre o sshfs rodando sshfs --help. No meu setup, eu monto a VM do Lima rodando sshfs lima-debian:/ ~/sshfs/lima. Então, se eu abro ~/sshfs/lima eu consigo ver os arquivos da minha VM:

Quais são as ferramentas que vêm à sua cabeça quando alguém diz “debug”? Deixa eu tentar adivinhar:

• um detector de vazamento de memória (ex: Valgrind);
• um profiler (ex: GNU gprof);
• uma função que para o seu programa e te dá um REPL (ex: a função breakpoint do Python ou o byebug do Ruby);
• alguma coisa que é de fato chamada depurador (ou “debugger”), como o GDB, ou algum similar que vêm nas IDEs;
• ou ainda a nossa velha amiga, a função print.

Certo, então neste texto eu tentarei te convencer a adicionar o Git a essa lista.

Quando você está versionando algum código com o Git, o repositório é uma preciosa fonte de informação. Muitas pessoas apenas pensam no Git só como aquele comando que em que se faz a sequência git add, git commit e git push, da mesma forma como se faria o upload de um arquivo para o Google Drive ou se postaria uma foto no Instagram. Porém, como o Git mantém todo o histórico de commits desde o mais antigo, ele é provavelmente a ferramenta que melhor conhece o código. Cada versão de cada arquivo é armazenada no repositório (neste texto estou me referindo por “repositório” o repositório local, não o do GitHub, GitLab, Bitbucket, etc), e achar informação útil nele é como um trabalho de arqueologia.

Então, vou então mostrar aqui alguns conceitos e ferramentas úteis para extrair tudo que você precisa a partir dele!

Recapitulando conceitos básicos

Antes de seguirmos em frente, vamos primeiro recapitular os conceitos básicos do Git.

Commits são as versões de um repositório. Eles são snapshots, não deltas, isso significa que um commit não sabe o que foi alterado. Em vez disso, um commit guarda o conteúdo de cada arquivo. Quando você executa git show, você não está olhando o conteúdo de um commit, você na verdade está olhando um patch, ou seja, o que mudou em relação ao commit pai. Essa mudança, porém, é feita de uma forma inteligente que economiza espaço.

Commits têm referências a seu(s) commit(s) pais (se houverem):

• um commit normal tem um único pai;
• um commit de merge tem dois pais;
• um commit de merge octopus tem dois ou mais pais;
• um commit inicial não tem pai.

Commits também armazenam quando e quem os criou!

Branches são só referências para commits. A bem da verdade, uma branch é só um arquivo que contém o hash de um commit;

O histórico de commits não é uma linha do tempo linear! Na verdade, é um DAG, um grafo acíclico direcionado, em outras palavras, ele é um conjunto de diferentes linhas do tempo que podem ter um passado em comum (uma bifurcação, ou fork point em inglês) e que podem ter estados onde timelines se encontram (um commit de merge), mas sem nenhum loop!

A área de staging, antigamente chamada de cache (nome ainda usado às vezes…) e internamente chamada de index é o lugar onde um commit é preparado (em outras palavras, é o lugar para onde você manda um arquivo quando executa git add). O conteúdo da área de staging é o conteúdo do seu último commit, além das alterações que você fez usando git add (aquelas que são mostradas em verde no git status).

O diretório de trabalho (em inglês, working directory) é o diretório onde estão armazenados no disco os arquivos do seu projeto. Da perspectiva deu quem está vendo ou de quem está escrevendo e executando o código, este pode parecer a principal área do Git (comparado ao histórico de comits e à área de staging). Porém, da perspectiva do Git, este é a menos importante, já que tudo aqui pode ser modificado, apagado, criado, e o Git não irá registrar, a não ser, claro, que você explicitamente diga a ele pra fazer isso (usando git add, por exemplo).

Se você não conhecia alguma coisa dessa seção, surigro fortemente que leia a seção 1.3 do livro Pro Git.

Pathspec e git ls-files

Vamos ao nosso primeiro conceito aqui: o pathspec (eu enrolo a língua pra falar essa palavra…). Um pathspec é uma string que pode ser passada como argumento para vários comandos do Git para especificar arquivos.

Uma forma legal de ver os pathspecs funcionando é usando git ls-files. Esse comando lista todos os arquivos na área de staging, porém, se você passar um pathspec como parâmetro, ele irá listar todos os arquivos que casam com esse pathspec.

O pathspec mais óbvio é o próprio enderço do arquivo. Se você tem um arquivo chamado README.md, então README.md vai ser um pathspec que o representa, e se ele está dentro de um diretório chamado src, um pathspec que irá identificá-lo é src/README.md. Note que, por padrão, pathspecs são relativos ao diretório atual

*

O primeiro superpoder do pathspec que irei mostrar a você é o *. Esse caracter casa com zero ou mais caracteres. Por exemplo, este comando lista todos os arquivos que terminam em .c na área de staging e que estão no diretório atual ou em seus subdiretórios, recursivamente:

git ls-files '*.c'

Talvez você esteja pensando: “nada novo até agora, é apenas uma expansão de *”. Bem, na verdade não. Note que '*.c' está entre aspas, isso significa que ele não é uma string, e o shell não está expandindo ele. Em vez disso, quem está fazendo a expansão é o próprio Git.

Mas qual é a diferença? Lembra que eu disse “no diretório atual ou em seus subdiretórios”? Essa é a diferença entre o * do pathspec e o do * do shell: nessa situação, o * do shell irá casar apenas com arquivos no diretório atual, enquanto que o pathspec * irá casar com todos os arquivos que estão no diretório atual ou em um subdiretório dele! Dessa forma, se executarmos:

git ls-files *.c

o shell irá substituir *.c por todos os arquivos que estão no diretório atual, então o git ls-files vai listar só eles.

: + palavras mágicas

: é um caracter especial para os pathspecs que é seguido de uma palavra mágina. Eu não irei entrar em detalhes sobre isso, mas existem dois casos que acho muito úteis.

O primeiro é o :/. Ele representa a raiz do repositório. Se você está em um subdiretório e quer achar arquivos pelos seus caminhos absolutos (isto é, relativos à raiz do repositório), você terá que usar :/. Por exemplo, :/*.c irá casar com todos os arquivos que terminam em .c no repositório, não importa onde eles estão localizados.

O segundo é :!. Se a gente colocar :! na frente de um pathspec, então o pathspec irá casar com todos os arquivos que não casam com o resto do pathspec. Por exemplo:

git ls-files ':!*.c'

Esse comando irá listar todos os arquivos na área de staging que não terminam em .c.

Mais sobre pathspecs e git ls-files

Pathspecs são realmente úteis para selecionar arquivos para passar como argumentos para o Git. Você pode ler mais sobre eles no glossário do Git (man gitglossary), procurando por “pathspec”.

O git ls-files, que eu usei como exemplo para os pathspecs, é uma ótima ferramenta para encontrar arquivos no repositório. Ele pode substiuir o comando find, já que tem uma sintaxe bem mais simples.

Git Grep

git grep, como o próprio nome diz, é um grep melhorado pelo Git.

E o que isso significa? Bom, lembra que eu disse que o Git é provavelmente a ferramenta que conhece o seu código? git grep se aproveita disso para fazer um grep melhorado.

A sintaxe do git grep é, basicamente, a seguinte:

git grep [<flags>] [<padrão>] [<commit>] -- [<pathspec>]

Você pode usar várias flags do grep no git grep, como por exemplo, -E, -P ou -i. O pathspec e o commit são opcionais. O -- é opcional na maior parte dos casos, porém, é recomendado usá-lo para evitar ambiguidades.

Se você passar umn commit, então o Git Grep vai procurar nele o padrão, mas só nele, não vai procurar em outros commits.

Se você não fornecer o pathspec, o Git Grep irá procurar pelo padrão em todos os arquivos no diretório atual ou em seus subdiretórios. Ele é bem mais rápido que o GNU Grep ou o BSD Grep. Você pode ver isso na imagem a seguir, nela eu estou procurando por #include no código fonte do próprio Git, usando BSD Grep, GNU Grep e Git Grep, respectivamente:

Mas o que mais o Git Grep pode fazer? Bom, dê uma olhada nas flags --heading e --break. --heading agrupa a saída pelo arquivo onde está cada linha, e --break apenas insere uma linha entre os grupos. Isso é muito útil para procurar, por exemplo, arquivos que chamam uma função ou usam uma constante.

Um recurso bem interessante do Git Grep é a flag -W (ou --show-function). Quando se ela, o Git Grep não só vai mostrar a linha que contém o que você está procurando, mas vai também mostrar toda a função onde ela está localizada. Então, vamos olhar o mesmo comando que eu mostrei na última imagem, porém, adicionando a flag -W (git grep --heading --break -W 'looks_like' -- '*.c'):

Git Grep é uma ferramenta incrível para encontrar código. Ok, mas você deve estar pensando “legal, mas eu consigo fazer algo parecido com isso com a navegação de código da minha IDE, pulando pra definições e para usos”. Isso é verdade para vários casos. Porém o Git Grep é realmente útil quando você quer procurar somente em alguns arquivos (usando um pathspec como restrição), quando você quer procurar por uma regex genérica em vez de um nome de uma variável ou função, quando você quer procurar em outro commit ou quando você só não quer abrir uam IDE e prefere procurar a partir do terminal. Não é uma ferramenta que substitui outras, e sim uma ferramenta complementa as outras.

Git Blame

Se você já usou alguma vez o git blame, é bem provável que vocẽ esteja esperando que eu fale sobre ele e como ele é maravilhoso. Se esse é o caso, então por favor, não pule esta seção porque eu tenho algo realmente importante para te dizer.

Se esse não é o caso e você nunca ouviu falar ou nunca usou o git blame, ele é uma ferramenta que mostra, para cada linha, quem foi a última pessoa que a mudou, qual foi o commit em que essa alteração foi feita, e a data e hora dessa mudança. Olhe para a imagem a seguir. Eu estou rodando git blame Main.hs, em que Main.hs é um arquivo que eu escrevi:

Legal, então, isso me mostra evidências para que eu possa xingar o código de alguém que trabalha comigo? Bom, na maior parte das vezes, sim, mas lembre-se: o git blame mostra apenas quem fez a última modificação. Talvez essa pessoa apenas mudou o nome de uma variável, aplicou uma mudança no estilo do código, moveu uma declaração de uma função para outro arquivo, ou qualquer outra mudança que seja na pratica seja quase irrelevante para o funcionamento do código. Muitas vezes a pessoa nem sabe o que o código faz (por exemplo, talvez a pessoa apenas executou uma ferramenta que formata código, sem nem ter lido ele).

Isso também se aplica à outra informação: a data e a hora que é mostrado é apenas a última vez que a linha foi alterada, e não nos diz quando ela foi criada. A mesma coisa vale para o commit: o commit que é mostrado é o útilmo commit que alterou alguma coisa na linha, não aquele que alterou alguma coisa útil ou o commit que primeiro adicionou aquela linha.

O Git Blame (e outras ferramentas baseadas nele, como o Annotate nas IDEs da JetBrains, o magit-blame no Emacs, ou o GitLens no VSCode) é sem dúvida bastante útil, porém, não é uma fonte da verdade. Se você quer saber algo além de apenas o que ocorreu na última mudança na linha, então você precisará de algo mais poderoso…

Git Log e seus poderes secretos

git log é um dos mais famosos comandos do Git. Ele é comando que você executa para ver o histórico de commits. Nada novo até aqui. Porém, ele tem alguns recursos menos conhecidos que eu considero como sendo o próximo passo para quando o Git Blame não é o suficiente para suas necessidades.

Passando um pathspec como argumento para o Git Log

Você pode restringir a saída do git log passando um pathspec como seu último argumento, assim: git log -- <pathspec>. De novo, o -- pode ser omitido na maior parte dos casos, porém, é uma boa prática mantê-lo para evitar ambiguidades.

Quando você faz isso, a saída irá conter apenas os commits que introduziram uma mudança nos arquivos que casam com o pathspec, em relação a seus commits anteriores. Olhe esse exemplo:

Se você quer saber quando alguma coisa foi introduzida, você pode inspecionar esses commits. Quando você encontrar em qual commit foi feita essa alteração, você irá descobrir quem e quando introduziu o commit. Se a mensagem de commit foi bem escrita e se a mudança foi atômica, você ainda saberá porque o commit foi criado (e porque o código existe). Se você está usando GitHub, você também poderá copiar o hash desse commit e procurar o Pull Request que o contém, e isso é ainda mais informação, já que você pode ler a discussão e a revisão de código!

Esse recurso do Git Log salvou minha vida várias vezes. Se eu encontrava um trecho de código que era difícil de entender para que servia, em vez de tentar lê-lo, eu usava o Git Log para encontrar o commit que o introduziu e entender o que a pessoa que o escreveu estava tentando fazer, qual o contexto dessa introdução, qual o problema que ela queria resolver, e assim por diante. Apenas tente fazer isso!

A flag -p

Apesar de tudo, pode ser bem entendiante olhar cada commit manualmente. Você pode usar -p para mostrar o patch de cada commit. Em outras palavras, é como executar git show para cada commit que aparece no log:

A flag -L

Talvez o arquivo seja muito longo e você só quer checkar o log de uma pequena porção dele. Então você pode usar a flag -L para restringir para a parte do código que te interessa. Ela tem duas variantes:

1. Você pode restringir pelos limites de um intervalo, que pode ser números de linhas ou expressão expressões regulares: git log -L <start>,<end>:<file>. Por exemplo: git log -L 10,20:my_file.c vai mostrar o log para o intervalo entre as linhas 10 e 20 do my_file.c;

2. (Eu acho esse ainda mais legal) Você pode ver o log de uma função: git log -L :<function>:<file>

Neste exemplo, estou vendo o log da função M412 do arquivo M412.cpp do Marlin usando git log -L :M412:M412.cpp:

A flag -S

A flag -S é um tesouro perdido no Git Log. Com ele, você pode ver todos os commits que aumentaram ou diminuíram o número de ocorrências de uma string. Pessoalmente falando, ele praticamente aposenta o Git Blame para mim: mesmo se uma pessoa moveu um trecho de código para outro lugar ou para outro arquivo, o git log -S vai conseguir encontrar a introdução dele.

Na imagem a seguir, eu estou usando git log -S para encontrar a primeira introdução de uma string contida no arquivo hardcoded_values.c (como você pode ver na saída do primeiro git grep). Depois, note que essa string não foi originalmente introduzida nesse arquivo (como você pode ver na saída do segudo git grep). A princípio, ele era parte do arquivo state_machine.c, então ele foi movido para outro arquivo. Isso resolve o problema do Git Blame apenas “culpar” a pessoa que moveu aquela linha, em vez da que a criou.

Você ainda pode usar -G em vez de -S. Isso permite usar uma expresão regular em vez de uma string.

Git Bisect

O git blame nos diz a última mudança de uma linha e o git log -S nos diz quando uma string foi introduzida ou removida. Porém, eles só operam sobre texto. Para vários casos isso é suficiente, porém, às vezes você não quer procurar por mudanças em um texto, mas quer procurar por mudanças no comportamento do programa, como novos bugs ou qualquer outra coisa que não esteja funcionando como esperado.

Nesses casos, o git blame ou o git log -S não serão suficientes, porque você não sabe qual código causou essa mudança de comportamento, e você não sabe exatamente o que procurar. Em projetos complexos, talvez essa mudança foi feita em um lugar que você nunca imaginaria, como por exemplo, em uma classe ou função que você pensou que não fosse relacionada à que quebrou.

E como o Git pode nos ajudar a encontrar essa mudança?

Senhoras e senhores, é uma honrar apresentar a vocês o meu comando favorito do Git: o Git Bisect! Ele nos permite encontrar o commit que quebrou alguma coisa no código. Dado um commit “bom” (um commit que não está quebrado, criado antes da introdução do bug), e um commit “ruim” (um commit em que o código certamente está quebrado), o Git irá fazer uma busca binária até que o commit quebrado seja encontrado.

Uma vez encontrado esse commit, você pode olhá-lo e conseguir todo o tipo de informação que discutimos anteriormente.

O Git Bisect pode ser usado de duas maneiras: uma mais manual, em que ele guia você até que o commit que introduziu o bug seja encontrado, e uma automática, que o Git encontra esse commit pra você.

Um exercício prático

Eu vou demonstrar o Git Bisect usando este repositório: https://github.com/lucasoshiro/bisect_demo. Ele é bem simples, apenas contém um único arquivo Python, com um código bem estranho e difícil de entender:

#!/usr/bin/env python3

from sys import argv
from math import log

ops = 0x2B2D2F2C2A5E3E5F

def func(a, b):
    return '\n'.join(
        (lambda r: f'{a} {f} {b} = {r}')(eval(f'{a}{f}{b}'))
        for f in ops.to_bytes((int(log(ops, 16)) + 1) // 2, 'big').decode())


if __name__ == '__main__':
    a, b = map(int, argv[1:])
    print(func(a, b))

E o que ele faz? Bom, ele recebe dois números como argumentos, e realiza algumas operações usando eles:

Ele funciona para a maior parte dos números, exceto se o segundo é 0. Como uma das operações é a divisão e como nós não estamos tratando erros de divisão por zero nesse código, esta entrada quebra o script:

Como você pode ver, nós sabemos onde o código está quebrando, porém, não conseguimos ver nenhuma operação de divisão nele. Se quisermos corrigir esse código, primeiro precisamos saber o que causou essa divisão, e isso não está claro aqui.

Claro que podemos executar git log aqui e tentar achar um commit que possa ter inserido esse bug. Porém, mesmo executando git log -p -- calc.py não será de grande ajuda. Veja:

Hora do Git Bisect nos salvar!

Rodando o Git Bisect manualmente

A primeira coisa que você precisa fazer é iniciar a bisseção (a busca binária, ou em inglês bisect), usando o comando git bisect start. Se você executar git status, ele mostrará que a bisseção foi iniciada. Alguns shells que mostram informações sobre o Git no prompt também mostram a bisseção foi iniciada. Se você já fez o que precisava com a bisseção, então você deve executar git bisect reset para terminá-la.

Eu disse que para fazermos a bisseção, precisamos de um “commit ruim” e um “commit bom”. Neste caso, nós sabemos que o último commit é ruim, já que ele quebra quando passamos 0 como segundo parâmetro.

Em um cenário real, provavelmente você saberá qual é um “bom” commit, ele será qualquer commit que contém um código que funciona, por exemplo, o commit da última release que não esteja quebrada. No caso deste exemplo, eu digo a você que o primeiro commit não tem bugs. Se você quiser ver isso, faça um checkout para ele e tente executar calc.py passando 0 como segundo argumento:

Dessa forma, agora sabemos um commit bom e um ruim, e nossa situação é esta (os commits estão em ordem cronológica, o primeiro commit é o primeiro):

8959689 Início     <- BOM!
f1a445e banana
e516236 goiaba
0acc414 Laranja
18c911e Toranja
0f3d5c7 Limão
7e27a60 Framboesa
f16e5e7 Morango
c3eb7db Carambola  <- RUIM!

E agora precisamos dizer ao Git Bisect sobre isso. Executamos git bisect good 8959689 para dizer que o commit inicial é bom. Como o commit atual é ruim, então podemos executar apenas git bisect bad para dizer ao Git Bisect isso, mas você poderia também executar git bisect bad c3eb7db, ou passar como argumento qualquer outro commit que você saiba que é ruim.

Depois de executar isso, o Git Bisect vai automaticamente fazer um checkout para o commit que está no meio do histório entre o bom e o ruim, ou seja, o commit 18c911e (Toranja). Após isso, executamos ./calc.py <algum número> 0 para decidir se esse commit é bom ou ruim.

Certo, então nossa situação é a seguinte:

8959689 Início     <- BOM!
f1a445e banana
e516236 goiaba
0acc414 Laranja
18c911e Toranja    <- RUIM!
0f3d5c7 Limão
7e27a60 Framboesa
f16e5e7 Morango
c3eb7db Carambola  <- RUIM!

E, novamente, precisamos dizer ao Git Bisect que esse commit é um dos ruins. Então, executamos git bisect bad. Como você deve imaginar, agora o Git Bisect vai fazer um checkout para o commit que está no meio dos commits 8959689 (Início) and 18c911e (Toranja). Esse commit é o e516236 (goiaba).

Agora fazemos a mesma coisa de antes: executamos ./calc.py <something> 0, vemos se ele quebra ou não, se sim então executamos git bisect bad, caso contrário executamos git bisect good, até que a busca binária termine e encontre o commit com problemas. Fazemos isso aqui:

Finalmente encontramos o commit que introduziu o bug: 0acc414 (Laranja). Agora você pode sair da bisseção com git bisect reset, e o Git irá voltar para o mesmo commit que você estava quando executou git bisect start. Se você está com curiosidade para saber porque essa mudança quebra o código, aqui está uma dica: 0x2F é o valor ASCII do caracter / em hexadecimal.

O Git Bisect é legal, porém, executá-lo manualmente dessa forma (verificando se um commit é bom ou ruim e em seguida executando git bisect bad ou git bisect good) pode ser bem entendiante. Dependendo da situação, é possível fazer isso de forma automática usando git bisect run!

Rodando o Git Bisect automaticamente

Caso exista um comando que diga se um commit é bom ou ruim, então o Git Bisect pode fazer a busca binária automaticamente! Esse comando pode ser qualquer coisa, como um shellscript, um script Python, um executável, um teste, entre várias outras coisas. O único requisito é que seu status code deve seguir algumas regras:

• Se o commit é bom, então o comando deverá devolver 0;
• Se o commit é ruim, então o comando deverá devolver qualquer coisa entre 1 e 127, inclusivamente, exceto 125;
• Se não é possível decidir se um commit é ruim ou bom, então ele precisa ser ignorado, e para isso o deverá devolver 125.

Neste exemplo, estamos verificando se o código lança uma exceção. Por padrão, quando um código termina sua execução em um exceção em Python, então seu status code é 1, ou é 0 quando a execução termina sem problemas. Então, apenas executar ./calc.py <algum número> 0 é suficiente, já que ele irá devolver 0 quando tudo terminou sem problemas e 1 quando um bug ocorreu. Porém, lembre-se de que esse não é sempre o caso, e dependendo é possível que você precise escrever um script de teste para tomar essa decisão.

Nós começamos a bisseção da mesma forma que antes:

git bisect start
git bisect good <hash do commit bom>
git bisect bad

Como queremos fazer a bisseção automática usando como critério ./calc.py 14 0, então executamos git bisect run ./calc.py 14 0. Funciona como mágica:

Depois disso, você também precisa executar git bisect reset para terminar a bisseção. E é isso. Não é legal?

Conclusão

Esses comandos me ajudaram muito quando eu navegava em bases de código bem grandes e preciava encontrar as causas bugs. Mas não apenas isso, eles podem ajudar a entender o código, por eles serem, essencialmente, ferramentas de busca. Simples e flexíveis, mas incrivelmente poderosas.

Obrigado pela leitura, se você encontrou algo errado ou tem alguma sugestão, abra uma issue no meu GitHub.

2024 update

Isto chegou em 5 no Hacker News!

Depois de receber alguns feedbacks, eu atualizei este post com git log -L:funcname:file, que eu não conhecia antes desta resposta!

Por exemplo, supondo que a estrutura do seu projeto seja esta a seguir, com dois arquivos Python (sendo um dentro de um subdiretório) e um diretório contendo uma biblioteca. Neste exemplo, essa biblioteca não é um diretório “copiado” para dentro do projeto, e sim um projeto separado mas que é incluído aqui através de um submódulo:

$ tree 

├── algum_arquivo.py
├── algum_diretorio
│   └── outro_arquivo.py
└── biblioteca_que_fica_em_submodulo
│   └── arquivo_da_biblioteca.py
└── .gitmodules

Como essa biblioteca é incluída via submódulo, sua versão ficará fixada em um commit até que alguém explicitamente a mude. Isso pode ser feito, por exemplo, da seguinte forma:

$ git -C biblioteca_que_fica_em_submodulo fetch
$ git -C biblioteca_que_fica_em_submodulo checkout <commit da versão nova>
$ git add biblioteca_que_fica_em_submodulo
$ git commit

Caso você tenha feito isso em uma branch sua e queira que essa alteração entre em outra branch, provavelmente você fará um merge. Supondo que essa outra branch seja a main e a sua seja chamada pr-branch:

$ git checkout main
$ git merge pr-branch

O grafo de commits ficaria assim, com as setas pontilhadas apontando para as versões dos submódulos:

Como a imagem mostra, queremos saber para qual commit do submódulo o commit de merge vai apontar.

Caso a main não tenha tido nenhuma alteração no submódulo enquanto você desenvolvia a pr-branch, o merge ocorre do jeito esperado e a biblioteca fica na versão nova. Caso contrário, o comportamento não é tão trivial:

• pode ser que a versão que esteja na main permaneça;
• pode ser que a que esteja na pr-branch permaneça;
• pode ser que aconteça um conflito que o Git não consiga resolver automaticamente sem intervenção de alguém.

A partir desse ponto, não encontrei algum material que explicasse de forma completa qual é o comportamento do Git nesses casos. Para entender o que acontece, precisei ir mais a fundo no Git, inclusive lendo o código fonte, e então resolvi escrever este post :-).

Breve explicação sobre objetos

Caso você já tenha familiaridade com o funcionamento dos objetos no Git, pode pular para a próxima seção. Aqui não é meu objetivo explicar a fundo como eles funcionam, só o que precisamos para entender o merge e os submódulos.

Então, caso você não tenha familiaridade com o funcionamento interno do Git, sugiro fortemente as seções 1.3 “What is Git?”, 10.2 “Git Objects” e 10.3 “Git References” do livro Pro Git, disponível gratuitamente em vários formatos em https://git-scm.com/book/en/v2.

Um tl;dr rápido com o que precisamos: os dados de um repositório (por “repositório” entenda o repositório local em cada máquina) é armazenado em unidades chamadas objetos. Esta é uma representação gráfica bem básica de como os objetos se relacionam entre si:

Um tipo de objeto é o nosso velho conhecido commit. Cada commit guarda o estado de todo o projeto no momento em que foi feito (e não apenas as alterações). Esse estado é chamado de snapshot, e pode ser entendido como uma “fotografia” do projeto naquele momento.

Outros tipos de objetos são tree e blob. Uma tree representa o estado de um diretório, sendo uma listagem de seus conteúdos: outros diretórios filhos (cada um com seu conteúdo representado por uma tree), ou arquivos (cada um com seu conteúdo representado por um blob).

Cada commit aponta para a tree que representa a raiz do projeto no estado que o commit guarda.

Cada commit aponta para seu(s) commit(s) pai(s), se houver:

• Um commit inicial não tem pai;
• Um commit comum tem apenas um pai;
• Um commit de merge tem dois ou mais pais, apontando para quais commits foram mesclados para que este commit fosse criado. Normalmente fazemos merge de apenas uma branch em outra, logo, o commit resultante normalmente tem dois pais.

Todo objeto é identificado por seu hash SHA-1. Objetos são únicos e imutáveis. Isso significa, por exemplo, que:

• dois arquivos iguais são representados pelo mesmo blob;
• dois diretórios iguais são representados pela mesma tree;
• um arquivo que tem o mesmo conteúdo em commits distintos é representado pelo mesmo blob em ambos;
• um arquivo que tem conteúdos diferentes em commits distintos é representado por blobs diferentes uns dos outros em cada um dos commits.

Uma branch não é um objeto. Ela é apenas uma referência, um ponteiro para um commit. Internamente, ela é simplesmente um arquivo com o hash de um commit dentro.

Breve explicação sobre merge

Fast-forward

Ainda no mesmo exemplo, quando fizemos git merge pr-branch, podemos ter uma situação que a pr-branch aponta para um commit descendente do commit que main aponta. Nesse caso, por padrão o Git não faz um merge verdadeiro, e sim um fast-forward. Isso significa que o Git simplesmente vai alterar a main para que aponte para o mesmo commit que a pr-branch.

Ilustrando como isso acontece, a situação antes do fast-forward era esta, com o grafo azul representando os commits do projeto, e o vermelho representando os commits do submódulo:

Depois do fast-forward:

Esse caso dispensa mais explicações quanto ao ponto principal do post, já que, obviamente, a biblioteca estará na mesma versão que a pr_branch após o fast-forward, já que a main passa a apontar para o mesmo commit que pr-branch.

Merge verdadeiro

Um merge verdadeiro ocorre caso o commit que pr_branch aponta não seja descendente do commit que main aponta, sendo então criado o commit com dois pais que mencionei anteriormente. Esse comportamento também pode ser forçado mesmo quando é possível um fast-forward, usando a flag --no-ff.

O git merge pode ter comportamentos distintos de acordo com a estratégia escolhida. Por padrão nas versões mais novas do Git a estratégia usada é a ort. Em versões um pouco mais antigas, a estretégia padrão é a recursive.

Este post irá abordar a partir daqui, o comportamento da ort. Porém, o que for abordado também vale para a recursive, mas não para as outras.

Three-way merge

A decisão sobre o que deve ser escolhido para entrar no commit de merge é feita por um algoritmo chamado three-way merge. Esse algoritmo se baseia em três commits: os dois commits apontados pelas branches que queremos fazer o merge, e o melhor ancestral comum desses dois commits.

Por “melhor ancestral comum” entre dois commits, entenda: um ancestral comum de dois commits X é melhor que outro ancestral comum Y se X for descendente de Y. O “melhor de todos” é o que será usado. Mais informações na manpage do git merge-base.

Nos três exemplos a seguir, o “melhor ancestral comum” das branches A e B é o commit amarelo:

Vamos denotar por A e B os dois commits apontados pelas branches que queremos fazer o merge, e por O o melhor ancestral comum a eles dois. Um arquivo poderá, então, ter até três versões diferentes, uma em A, uma em B e outra em O.

Para tomar a decisão de qual será usada, o three-way merge faz a seguinte regra:

• Se o arquivo tem o mesmo conteúdo em A e em B, no commit de merge ele terá esse conteúdo;
• Caso contrário:
  • Se o arquivo tem o mesmo conteúdo em A e em O, no commit de merge ele terá o conteúdo de B;
  • Se o arquivo tem o mesmo conteúdo em B e em O, no commit de merge ele terá o conteúdo de A;
• Caso contrário (o arquivo tem conteúdos distintos entre si em A, B e O): conflito.

Podemos ver isso na imagem a seguir. As bolinhas representam conteúdos diferentes do mesmo arquivo ao longo dos commits.

A comparação entre os estados não é feita usando o arquivo inteiro: o Git compara o hash dos blobs em cada um dos estados, o que é suficiente pra dizer se eles são iguais ou não (lembrando: caso o arquivo seja igual em commits diferentes, ele é representado pelo mesmo blob).

Caso haja um conflito e o arquivo for um arquivo de texto puro, o Git por padrão ainda faz o three-way merge internamente no conteúdo. Dessa forma, por exemplo, se a mudança de O para A seja em um local distinto de O pra B dentro do arquivo, ambas são preservadas. Caso elas tenham sido feitas no mesmo local, o Git adiciona as marcas de conflito para que sejam resolvidas pelo usuário (aquelas <<<<<<<, ======= e >>>>>>>).

Arquivos binários não são resolvidos, o usuário deverá escolher qual versão que deverá ser usada no commit de merge.

Breve explicação sobre submódulos

Bom, se você chegou até aqui, provavelmente não precisa de uma introdução aos submódulos. Mas ainda assim, vale a pena mostrar como eles são representados internamente.

Vimos que cada tree representa o conteúdo de um diretório. Com o comando git ls-tree podemos ver o conteúdo de uma tree . Se fizermos git ls-tree HEAD podemos verificar o conteúdo da tree do commit atual. No nosso exemplo, seria algo parecido com isso:

$ git ls-tree HEAD
100644 blob 123abc456def123abc456def123abc456def9999 .gitmodules
100644 blob 1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4d5e6f1234 algum_arquivo.py
040000 tree aaaaabbbbbcccccdddddeeeeefffff1111122222 algum_diretorio
160000 commit fedcba0123456789fedcba012345678912345678 biblioteca_que_fica_em_submodulo

Os hashes nas linhas do algum_arquivo.py e do .gitmodules indicam os blobs que armazenam seus respectivos conteúdos, e da mesma forma, o hash na linha de algum_diretorio indica a tree que armazena o conteúdo desse diretório.

Porém, na linha da biblioteca_que_fica_em_submodulo, o hash que aparece é justamente o hash do commit do submódulo referente à versão atual da biblioteca. Caso seja feita uma alteração da versão dessa biblioteca, esse hash muda, consequentemente a tree que representa o diretório raiz do projeto será outro objeto, ou seja, será outro snapshot.

Ilustrando isso, os submódulos ficam assim:

Além disso, ainda temos o arquivo .gitmodules, que armazena propriedades dos submódulos, como, por exemplo, seu diretório (path) e a URL do repositório de onde ele é clonado (url). Mais informações sobre o .gitmodules estão na sua manpage.

Three-way merge de submódulos

O three-way merge ainda valerá se fizermos o merge de commits que tenham submódulos. E o mecanismo é o mesmo que serviria para fazer o three-way merge de arquivos, porém, em vez de comparar hashes de blobs, comparamos hashes de commits do submódulo:

• Se o submódulo aponta para o mesmo commit em A e B, esse commit será usado no commit de merge;
• Caso contrário:
  • Se o submódulo aponta para o mesmo commit em A e em O, o commit para que ele aponta em B será usado no commit de merge;
  • Se o submódulo aponta para o mesmo commit em B e em O, o commit para que ele aponta em A será usado no commit de merge;
• Caso contrário (o submódulo aponta para commits distintos em A, B e O): conflito.

Tudo tranquilo até aqui, mas o que acontece quando temos um conflito…

Resolução de conflitos de submódulos

Caso haja um conflito entre submódulos, dependendo da situação o Git tenta resolver automaticamente: caso o commit do submódulo em A seja descendente do commit do submódulo em B, o commit do submódulo em A será usado. O contrário também vale: caso o commit do submódulo em B seja descendente do commit do submódulo em A, o commit do submódulo em B será usado. Esse comportamento você pode ver aqui, no código-fonte do Git. Em outras palavras, é feito um fast-forward no submódulo.

Graficamente, a situação antes era esta:

Depois do merge com fast-forward de submódulo, a situação é esta:

Caso não seja possível esse fast-forward, o Git indica conflito e o usuário deverá resolver manualmente, como nesta situação:

Ainda assim, caso esses commits não sejam descendentes um do outro mas exista algum commit de merge que seja descendente de ambos, esse commit será sugerido para o usuário como uma possível solução para usar como commit do submódulo no merge, e cabe ao usuário aceitá-la ou não. Esse comportamento pode ser visto aqui, no código-fonte do Git.

Vale ressaltar também que essas formas de resolução de conflitos só são possíveis caso estejam presentes localmente os objetos referentes aos commits do submódulo. Caso eles não estejam presentes (por exemplo, por um git clone sem --recursive, ou por falta de um git submodule update), o Git não será capaz de resolver e irá indicar conflito.

E o GitHub e o GitLab?

A libgit2 é uma biblioteca em C que provê as funcionalidades do Git. Segundo o README da libgit2, tanto o GitHub e o GitLab trabalham usando a libgit2. A libgit2 não tenta resolver conflitos de submódulos, como pode ser visto aqui, no código-fonte da libgit2, e isso também vale para o GitHub e o GitLab.

Para ver isso na prática:

$ git checkout main
$ git submodule update --init
$ git branch pr-branch

# Adicionando um commit à main
$ git -C biblioteca_que_fica_em_submodulo checkout algum_commit~ # esse ~ é proposital
$ git add biblioteca_que_fica_em_submodulo
$ git commit

# Adicionando um commit à pr-branch
$ git checkout pr-branch
$ git submodule update --init
$ git -C biblioteca_que_fica_em_submodulo checkout algum_commit # descendente do commit na main
$ git add biblioteca_que_fica_em_submodulo
$ git commit

# Git push, para fazermos um PR/MR logo em seguida
$ git push origin pr-branch # supondo que seu remote se chame origin

Chegamos a uma situação parecida com esta:

Localmente, nesse caso um git checkout main && git merge pr-branch funciona, porque o Git fará um fast-forward do submódulo. Mas se você abrir um Pull Request (GitHub) ou Merge Request (GitLab) para a branch pr-branch, vai ser indicado um conflito no submódulo.

Como resolver?

Caso você esteja nessa situação, pode fazer isto:

$ git fetch origin main # supondo que seu remote se chame "origin"
$ git checkout pr-branch
$ git submodule update --init
$ git merge origin/main
$ git push origin pr-branch # supondo que seu remote se chame "origin"

O que deixará o grafo de commits nesta situação:

O PR/MR não estará mais com conflito. E por que funciona? Bom, fizemos um merge da main na pr-branch, o que localmente é bem-sucedido já que o Git foi capaz de fazer um fast-forward do submódulo.

Quando fizermos o push:

1. Se ninguém alterar a main nesse meio-tempo, pr-branch será descendente da main, o que permite um fast-forward;
2. Caso alguém tenha alterado a main nesse meio-tempo, a main antiga (que você fez o fetch) será a melhor ancestral comum entre a main nova (com a alteração da outra pessoa) e pr-branch. Dessa forma, caso a main nova não tenha alterado o submódulo em relação à main antiga, o submódulo da pr-branch será escolhido no three-way merge. Isso também valerá caso você opte por não usar um fast-forward no GitHub/GitLab.

Conclusão

Quando fazemos git merge pr-branch, o Git tenta mesclar os submódulos usando three-way merge. Se não for possível, tenta um fast-forward para o commit descendente do submódulo, se houver. GitHub e GitLab não fazem esse fast-forward, então, precisamos fazer o merge localmente, resolvendo o conflito do submódulo manualmente ou automaticamente, de forma que permita o que o GitHub ou GitLab façam o three-way merge sem cair no caso de conflito.