backup-git

Pacote npm para registrar alterações e confirmar seu envio ao remoto Git. A ferramenta é instalada no projeto e não depende dos comandos globais backup_git ou backup_git_5m.

Requisitos: Node.js 20 ou superior, npm, Git e autenticação no remoto em cada computador. Sem dependências npm externas. Versão inicial desta estrutura: 2.0.0, preservada do manifesto existente da v011.

Usar e validar esta fonte

Dentro de backup_git/v011:

npm ci
npm run backup:version
npm test
node backup-git.js --help

npm ci, instalação do pacote, ajuda e versão não executam backups. Não há scripts de instalação que iniciem processos ou alterem o shell.

Para executar em um repositório escolhido explicitamente:

node backup-git.js status --repo /caminho/do/projeto
node backup-git.js backup --repo /caminho/do/projeto

O backup inclui todo o repositório Git, incluindo pastas irmãs da pasta de execução e exclusões. Se executado nesta v011 sem --repo, trabalha no repositório pai backup_git, com todas as versões. O status consulta o remoto (precisa de rede), atualiza metadados de fetch e não cria commits nem altera arquivos de trabalho. synchronized só é verdadeiro com históricos iguais e sem alterações locais visíveis ao Git.

Gerar o pacote instalável

npm pack

Isso executa a checagem de sintaxe e os testes antes de gerar backup-git-2.0.0.tgz. O pacote contém apenas o executável, biblioteca, manifesto, README e changelog. O tarball não depende do checkout de origem depois de instalado.

Instalação pelo npm após publicação

Na pasta npm do projeto consumidor (por exemplo tools/modules/backup_git):

npm install --save-dev --save-exact [email protected]

Registre os scripts backup, backup:status e backup:version como no exemplo abaixo. Versione package.json e package-lock.json; nos outros computadores execute npm ci. Para atualizar, instale explicitamente a versão desejada com npm install --save-dev --save-exact backup-git@VERSAO. Consulte npm view backup-git version para ver a versão publicada. A instalação pelo registry estará disponível somente após publicação confirmada.

Instalar localmente por tarball

Exemplo partindo da raiz do projeto consumidor, com o tarball gerado acima:

mkdir -p tools/modules/backup_git/vendor
cp /caminho/backup_git/v011/backup-git-2.0.0.tgz tools/modules/backup_git/vendor/
cd tools/modules/backup_git
npm init -y
npm install --save-dev --save-exact ./vendor/backup-git-2.0.0.tgz
npm pkg set 'scripts.backup=backup-git'
npm pkg set 'scripts.backup:status=backup-git status'
npm pkg set 'scripts.backup:version=backup-git --version'

Crie também um .gitignore nessa pasta com:

node_modules/
!vendor/*.tgz

Versione package.json, package-lock.json, .gitignore e o tarball em vendor/. Mantenha o tarball: o lockfile aponta para ele. Não versione node_modules. Caso o projeto já tenha um módulo npm nessa pasta, preserve seu manifesto e acrescente somente a dependência e os scripts.

Para usar:

npm run backup:version
npm run backup:status
npm run backup

Também são disponibilizados os nomes backup_git e backup_github nos executáveis locais do npm. Não instale com sudo ou -g para este fluxo.

Continuar em outro computador

Depois de clonar/atualizar o projeto, entre em tools/modules/backup_git e execute npm ci. Os manifestos e o tarball versionados permitem reinstalar a mesma versão. Cada computador precisa ter sua identidade Git e acesso ao remoto configurados.

Este repositório guarda o pacote em uma subpasta (v011); npm install github:... na raiz do repositório não seleciona essa subpasta. A distribuição por tarball continua disponível; publicação npm é uma etapa explícita. Nenhuma release GitHub é criada pelo empacotamento.

Atualizar ou voltar de versão

Ao preparar uma atualização da ferramenta, altere a versão no package.json, sincronize o lockfile com npm install --package-lock-only e gere outro tarball com npm pack. Não é necessário criar outra pasta de versão do projeto.

No consumidor, copie o novo tarball para vendor/ e execute npm install --save-dev --save-exact ./vendor/backup-git-NOVA-VERSAO.tgz, substituindo NOVA-VERSAO pela versão real. Confira npm run backup:version, valide e versione os manifestos e o tarball. Para voltar, reinstale o tarball anterior, preservado em vendor/ ou no histórico Git. Não há atualização automática durante o backup.

Comportamento do backup

1. Detecta a raiz, branch e upstream remoto já configurado. Recusa HEAD destacado, operações Git incompletas e conflitos no índice.
2. Adquire um lock local nos metadados Git e recupera locks válidos de processos encerrados no mesmo computador.
3. Confere arquivos considerados pelo Git. Arquivos de 100 MiB ou mais interrompem a operação: nada é ignorado silenciosamente e o .gitignore não é reescrito. Arquivos ignorados permanecem fora do backup.
4. Registra arquivos novos, modificados e excluídos em commit local. Se a rede falhar depois disso, o commit fica preservado para reenvio.
5. Consulta a branch remota. Se os dois computadores criaram commits diferentes, informa divergência e interrompe, preservando os históricos. A integração precisa ser resolvida antes de reenviar. Se apenas o remoto avançou, atualiza por fast-forward.
6. Tenta enviar mesmo sem alterações novas e só informa sucesso após confirmar o hash no remoto. Não usa force push ou reset.

Saída 0 indica execução concluída; 1 indica erro. Em status, saída 0 significa consulta concluída; examine ahead, behind, changes e synchronized para saber se há pendências. Falha de rede/autenticação não equivale a backup online concluído.

Limitações: requer branch com commit inicial e upstream existente; não cria repositórios/remotos, não configura Git LFS, não resolve divergências e não instala agendamento. Hooks Git existentes continuam sendo executados pelo Git. Operações manuais de Git ou outras ferramentas não respeitam necessariamente o lock deste pacote. O limite de arquivos não substitui restrições próprias do servidor nem analisa todo o histórico antigo. Testado em Linux com Node.js 20 e remotos Git locais; não validado em Windows/macOS.

Testes

npm test usa o runner nativo do Node.js e repositórios temporários, com remotos bare locais. Cobre reenvio após rejeição, indisponibilidade do remoto, dois computadores, fast-forward, exclusões, arquivos ignorados/grandes, nomes especiais, links e locks. Nenhum teste envia ao GitHub ou executa o backup global.