Git LFS

Quando você faz o checkout de um commit que contém ponteiros do Git LFS, eles são substituídos por arquivos do cache local do Git LFS ou baixados do armazenamento remoto do Git LFS.

O Git LFS é simples: na sua cópia de trabalho, você vai ver apenas o conteúdo real do arquivo. Ou seja: você pode usar o Git LFS sem alterar seu fluxo de trabalho existente do Git; basta fazer o git checkout, a edição, o git add e o git commit normalmente. As operações git clone e git pull vão ser significativamente mais rápidas, pois você só baixa as versões de arquivos grandes referenciados por commits que você realmente fez checkout, em vez de todas as versões do arquivo que já existiram.

Para usar o Git LFS, você vai precisar de um host compatível com Git LFS, como o Bitbucket Cloud ou o Bitbucket Data Center. Os usuários do repositório vão precisar ter o cliente de linha de comando Git LFS instalado ou um cliente GUI compatível com Git LFS, como o Sourcetree. Curiosidade: Steve Streeting, o desenvolvedor da Atlassian que inventou o Sourcetree, também é um grande colaborador do projeto Git LFS, então o Sourcetree e o Git LFS trabalham juntos muito bem.

1. Existem três maneiras fáceis de instalar o Git LFS:

a. Instale-o usando seu gerenciador de pacotes favorito. pacotes git-lfs estão disponíveis para Homebrew, MacPorts, DNF e packagecloud; ou

b. Faça o download e instale o Git LFS no site do projeto; ou

c. Instale o Sourcetree, um cliente de GUI de Git gratuito que vem com o Git LFS.

2. Quando o git-lfs estiver no caminho, execute git lfs install para inicializar o Git LFS (você pode pular esta etapa se tiver instalado o Sourcetree):

Você só vai precisar executar o git lfs install uma vez. Depois de inicializado para o seu sistema, o Git LFS vai inicializar automaticamente quando você clonar um repositório contendo conteúdo do Git LFS.

Para criar um novo repositório compatível com Git LFS, você vai precisar executar o git lfs install depois de criar o repositório:

Esse comando instala um hook pre-push especial do Git em seu repositório que vai transferir arquivos Git LFS para o servidor quando você fizer o git push.

O Git LFS é ativado automaticamente para todos os repositórios do Bitbucket Cloud. Para o Bitbucket Data Center, você vai precisar habilitar o Git LFS nas configurações do seu repositório:

Depois que o Git LFS for inicializado para seu repositório, você vai poder especificar quais arquivos rastrear usando o git lfs track.

Depois que o Git LFS estiver instalado, você vai poder clonar um repositório Git LFS normalmente usando git clone. No final do processo de clonagem, o Git vai fazer o checkout do branch padrão (em geral main), e todos os arquivos Git LFS necessários para concluir o processo de checkout vão ser baixados automaticamente para você. Por exemplo:

Há quatro PNGs neste repositório sendo rastreados pelo Git LFS. Ao executar o git clone, os arquivos do Git LFS são baixados um de cada vez, à medida que os arquivos de ponteiro são retirados do seu repositório.

Se você estiver clonando um repositório com um grande número de arquivos LFS, o comando git lfs clone explícito oferece um desempenho muito melhor:

Em vez de baixar os arquivos Git LFS um de cada vez, o comando git lfs clone aguarda até que o checkout seja concluído e, em seguida, baixa todos os arquivos Git LFS necessários como um lote. Assim ele aproveita os downloads paralelos e reduz drasticamente o número de solicitações HTTP e processos gerados (o que é especialmente importante para melhorar o desempenho no Windows).

Assim como a clonagem, você pode extrair de um repositório Git LFS usando um git pull normal. Todos os arquivos Git LFS necessários vão ser baixados como parte do processo de checkout automático assim que o pull for concluído:

Nenhum comando explícito é necessário para recuperar o conteúdo do Git LFS. No entanto, se o checkout falhar por um motivo inesperado, você vai poder baixar qualquer conteúdo do Git LFS ausente para o commit atual com git lfs pull:

Como o git lfs clone, o git lfs pull baixa seus arquivos Git LFS como um lote. Se você sabe que um grande número de arquivos foi alterado desde a última vez que você puxou, você pode querer desabilitar o download automático do Git LFS durante o checkout e, em seguida, fazer o download em lote do seu conteúdo Git LFS com um git lfs pull explícito. Essa ação pode ser feita substituindo sua configuração do Git pela opção -c quando você invoca o git pull:

Já que é bastante coisa para digitar, você pode querer criar um alias Git simples para executar um pull em lote do Git e do Git LFS para você:

Assim o desempenho vai melhorar muito quando um grande número de arquivos Git LFS precisar ser baixado (de novo, especialmente no Windows).

Quando você adiciona um novo tipo de arquivo grande ao seu repositório, você vai precisar dizer ao Git LFS para rastreá-lo especificando um padrão usando o comando git lfs track:

Observe que as aspas em torno de "e*.ogg" são importantes. A omissão delas vai fazer com que o caractere curinga seja expandido pelo shell, e entradas individuais vão ser criadas para cada arquivo .ogg no diretório atual:

Os padrões com suporte pelo Git LFS são os mesmos que o .gitignore, por exemplo:

Esses padrões são relativos ao diretório no qual você executou o comando git lfs track. Para manter as coisas simples, é melhor executar o git lfs track a partir da raiz do seu repositório. Observe que o Git LFS não suporta padrões negativos como .gitignore faz.

Depois de executar o git lfs track, você vai notar um novo arquivo chamado .gitattributes no diretório do qual você executou o comando. .gitattributes é um mecanismo do Git para vincular comportamentos especiais a certos padrões de arquivo. O Git LFS cria ou atualiza automaticamente o .gitattributes arquivos para vincular padrões de arquivos rastreados ao filtro Git LFS. No entanto, você vai precisar fazer o commit de todas as alterações no .gitattributes arquivo para seu repositório você mesmo:

Para facilitar a manutenção, é mais simples manter todos os padrões do Git LFS em um único arquivo .gitattributes sempre executando git lfs track a partir da raiz do seu repositório. No entanto, você pode exibir uma lista de todos os padrões que são atualmente rastreados pelo Git LFS (e os arquivos .gitattributes nos quais eles são definidos) invocando git lfs track sem argumentos:

Você pode parar de rastrear um padrão específico com o Git LFS apenas removendo a linha apropriada do seu arquivo .gitattributes, ou executando o comando git lfs untrack:

Depois de executar git lfs untrack, você vai ter que fazer o commit das alterações em .gitattributes de novo por conta própria.

Você pode fazer commit e push normalmente para um repositório que contém conteúdo do Git LFS. Se você tiver feito o commit de alterações em arquivos rastreados pelo Git LFS, vai ver algumas saídas adicionais do git push à medida que o conteúdo do Git LFS for transferido para o servidor:

Se a transferência dos arquivos LFS falhar por algum motivo, o push vai ser abortado, e você vai poder tentar novamente com segurança. Como o Git, o armazenamento Git LFS é endereçável ao conteúdo: o conteúdo é armazenado em uma chave que é um hash SHA-256 do próprio conteúdo. Ou seja: é sempre seguro tentar transferir arquivos Git LFS para o servidor de novo; você não pode substituir acidentalmente o conteúdo de um arquivo Git LFS com a versão errada.

Para migrar um repositório Git LFS de um provedor de hospedagem para outro, você pode usar uma combinação de git lfs fetch e git lfs push com a opção --all especificada.

Por exemplo, mover todos os repositórios Git e Git LFS de um remoto chamado github para um remoto chamado bitbucket 😉:

Normalmente, o Git LFS baixa apenas os arquivos necessários para commits de que você realmente faz o checkout no local. No entanto, você pode forçar o Git LFS a baixar conteúdo extra para outros branches modificados recentemente usando git lfs fetch --recent:

Essa opção é útil para o download em lote do novo conteúdo do Git LFS enquanto você estiver no almoço, ou se estiver planejando revisar o trabalho de seus colegas de equipe e não conseguir baixar o conteúdo mais tarde devido à conectividade limitada com a Internet. Por exemplo, você pode querer executar git lfs fetch --recent antes de pular em um avião!

O Git LFS considera qualquer branch ou tag que contenha um commit mais recente do que sete dias. Você pode configurar o número de dias considerados recentes definindo a propriedade lfs.fetchrecentrefsdays:

Por padrão, git lfs fetch --recent só vai baixar o conteúdo do Git LFS para o commit na ponta de um branch ou tag recente.

No entanto, você pode configurar o Git LFS para baixar conteúdo para commits anteriores em branches e tags recentes configurando a propriedade lfs.fetchrecentcommitsdays:

Use essa configuração com cuidado: se você tiver branches muito dinâmicos, pode ficar com o download de uma grande quantidade de dados. No entanto, pode ser útil se você precisar revisar as alterações intersticiais em um branch, selecionar commits entre branches ou reescrever o histórico.

Conforme discutido em Movendo um repositório Git LFS entre hosts, você também pode optar por buscar todo o conteúdo do Git LFS para seu repositório com o git lfs fetch --all:

Você pode excluir arquivos do cache local do Git LFS com o comando git lfs prune:

Assim todos os arquivos Git LFS locais considerados antigos vão ser excluídos. Um arquivo antigo é qualquer arquivo não referenciado pelo:

• commit do checkout atual
• um commit que ainda não foi enviado (para a origem, ou para o que quer que o lfs.pruneremotetocheck esteja definido)
• um commit recente

Por padrão, um commit recente é qualquer commit criado nos últimos dez dias. O cálculo é feito adicionando:

• o valor da propriedade lfs.fetchrecentrefsdays discutida em Obtendo histórico extra do Git LFS (cujo padrão é sete); para
• o valor da propriedade lfs.pruneoffsetdays (sendo que o padrão é de três)

Você pode configurar o deslocamento de remoção para reter o conteúdo do Git LFS por um período mais longo:

Ao contrário da coleta de lixo integrada do Git, o conteúdo do Git LFS não é removido automaticamente, portanto, executar o git lfs prune regularmente é uma boa ideia para manter o tamanho do repositório local baixo.

Você pode testar o efeito que uma operação de remoção vai ter com o git lfs prune --dry-run:

E exatamente quais objetos do Git LFS vão ser removidos com git lfs prune --verbose --dry-run:

As strings hexadecimais longas produzidas pelo modo —verbose são hashes SHA-256 (também conhecidos como IDs de objeto ou OIDs) dos objetos Git LFS a serem removidos. Você pode usar as técnicas descritas em Localizando caminhos ou commits que fazem referência a um objeto Git LFS para saber mais sobre os objetos que vão ser removidos.

Como uma verificação de segurança adicional, você pode usar a opção --verify-remote para verificar se o armazenamento remoto do Git LFS tem uma cópia dos seus objetos Git LFS antes de serem removidos:

Assim o processo de remoção fica significativamente mais lento, mas você ganha a tranquilidade de saber que todos os objetos removidos podem ser recuperados do servidor. Você pode habilitar a opção --verify-remote permanentemente para o seu sistema configurando a propriedade lfs.pruneverifyremotealways globalmente:

Ou você pode habilitar a verificação remota apenas para o repositório de contexto omitindo a opção --global do comando acima.

O cliente de linha de comando Git LFS não suporta a remoção de arquivos do servidor, portanto, como você os exclui depende do seu provedor de hospedagem.

No Bitbucket Cloud, você pode visualizar e excluir arquivos Git LFS por meio das Configurações do repositório> Git LFS:

Observe que cada arquivo Git LFS é indexado por seu SHA-256 OID; os caminhos que fazem referência a cada arquivo não são visíveis por meio da interface do usuário. Esse comportamento ocorre porque pode haver muitos caminhos diferentes em muitos commits diferentes que podem se referir a um determinado objeto, portanto, procurá-los seria um processo muito lento.

Para determinar o que um determinado arquivo Git LFS realmente contém, você tem três opções:

• ver a imagem de visualização do arquivo e o tipo de arquivo na coluna da esquerda da interface do usuário do Bitbucket Git LFS
• baixar o arquivo usando o link na coluna da direita da interface do usuário do Bitbucket Git LFS -pesquisar commits que fazem referência ao SHA-256 OID do objeto Git LFS, conforme discutido na próxima seção

Se você tiver um Git LFS SHA-256 OID, vai poder determinar quais commits fazem referência a ele com git log --all -p -S :

Esse encantamento do git log gera um patch (-p) a partir de commits em qualquer branch (--all) que adiciona ou remove uma linha (-S) contendo a string especificada (um Git LFS SHA-256 OID).

O patch mostra o commit e o caminho para o objeto LFS, bem como quem o adicionou e quando foi feito o commit dele. Você pode simplesmente fazer o checkout do commit, e o Git LFS vai fazer o download do arquivo, se necessário, e colocá-lo em sua cópia de trabalho.

Se você suspeitar que um determinado objeto Git LFS está em seu HEAD atual ou em um branch específico, você pode usar git grep para encontrar o caminho do arquivo que faz referência a ele:

Você pode substituir HEAD ou power-ups por qualquer ref, commit ou árvore que contenha o objeto Git LFS.

Em algumas situações, você pode querer baixar apenas um subconjunto do conteúdo disponível do Git LFS para um commit específico. Por exemplo, ao configurar um build de integração contínua para executar testes de unidade, você pode precisar apenas do seu código-fonte, portanto, pode querer excluir arquivos pesados que não são necessários para criar seu código.

Você pode excluir um padrão ou subdiretório usando git lfs fetch -X (ou --exclude):

Como alternativa, você pode querer incluir apenas um padrão ou subdiretório específico. Por exemplo, um engenheiro de áudio pode buscar apenas arquivos ogg e wav com git lfs fetch -I (ou --include):

Se você combinar inclusões e exclusões, somente os arquivos que corresponderem a um padrão de inclusão e não corresponderem a um padrão de exclusão vão ser buscados. Por exemplo, você pode buscar tudo em seu diretório Assets, exceto gifs com:

Exclui e inclui suporte aos mesmos padrões que o git lfs track e .gitignore. Você pode tornar esses padrões permanentes para um repositório específico definindo as propriedades de configuração lfs.fetchinclude e lfs.fetchexclude:

Essas configurações também podem ser aplicadas a todos os repositórios do sistema, anexando a opção --global.

Infelizmente, não existe uma maneira fácil de resolver conflitos de binários no merge. Com o bloqueio de arquivos do Git LFS, você pode bloquear arquivos por extensão ou por nome de arquivo e impedir que arquivos binários sejam substituídos durante um merge.

Para aproveitar a característica de bloqueio de arquivos do LFS, primeiro você precisa informar ao Git quais tipos de arquivos podem ser bloqueados. No exemplo abaixo, a marcação `--lockable` é anexada ao comando `git lfs track` que armazena arquivos PSD no LFS e os marca como bloqueáveis.

Em seguida, adicione o seguinte ao seu .gitattributes :

Ao se preparar para fazer alterações em um arquivo LFS, você vai usar o comando lock para registrar o arquivo como bloqueado em seu servidor Git.

Quando não precisar mais do bloqueio de arquivo, você vai poder removê-lo usando o comando de desbloqueio do Git LFS.

Os bloqueios de arquivo Git LFS podem ser substituídos, semelhante ao git push, usando uma marcação --force. Não use a marcação --force a menos que tenha absoluta certeza do que está fazendo.