Versionamento (Git fácil)

Git, GitHub e a nuvem

O Git é local. Ele é um programa grátis que roda no seu computador e guarda o histórico de versões dentro da própria pasta, na pasta oculta .git. Ligar o versionamento não envia nada para a internet e não pede conta nenhuma: as versões ficam só nesta máquina — e, se o disco falhar ou o computador for perdido, elas vão junto.

O GitHub é outra coisa: um serviço na nuvem que guarda uma cópia do repositório. É para ele, ou para um serviço parecido, que o LightNote envia as versões quando você sincroniza. Com essa cópia fora daqui você ganha um backup e pode usar as mesmas notas em outro computador: num você envia, no outro recebe. O GitHub é grátis para uso pessoal, com repositórios privados ilimitados, que só você vê.

Em resumo: o Git são as versões, no seu computador; o remoto é uma cópia delas em outro lugar — o GitHub, outro serviço, uma pasta do OneDrive ou do Google Drive, ou um servidor seu. Enquanto a pasta não tem remoto, o painel de versionamento diz Versões só neste computador e oferece o link Fazer backup e sincronizar…, explicado abaixo.

Clonar um repositório

Para trabalhar num repositório que já existe, use Arquivo → Clonar repositório Git... — o item também está na tela inicial e no painel de versionamento de uma pasta ainda sem repositório. Cole o endereço HTTPS ou SSH que a página do repositório mostra; a URL da própria página serve, e um git clone ... copiado inteiro também. Escolha a pasta-base e o nome da pasta: o assistente mostra onde ela vai nascer e avisa quando já existe algo ali. Em Opções avançadas ficam o branch, o clone raso (só o último commit) e os submódulos.

Quando o servidor pede login, o LightNote pergunta numa janela: usuário e token, a senha da chave SSH, ou a confirmação da chave de um servidor que este computador nunca viu — nesse caso a janela mostra a impressão digital e o link para a lista que o serviço publica, e o padrão é não confiar. A resposta vai direto para o Git e o LightNote não a guarda; quem guarda é o gerenciador de credenciais do Git, quando ele está instalado (o Git for Windows traz o Git Credential Manager). Confiar na chave grava-a em ~/.ssh/known_hosts, como o próprio ssh faria.

Se o clone falhar, a tela diz o que houve e oferece a saída: tentar por HTTPS quando a chave SSH foi recusada, usar os certificados do Windows quando o proxy da empresa inspeciona o HTTPS, baixar só o último commit quando a conexão cai no meio, ou usar caminhos longos quando o Windows não deixa criar o arquivo. Os Detalhes técnicos trazem a mensagem do Git, e o que não se reconhece pode ir para a IA. Ao terminar, o assistente abre a pasta clonada nesta janela ou numa nova.

Versionar a pasta aberta

O versionamento é opt-in por espaço. Ative em Ferramentas → Espaço → Configuração do Espaço...: o LightNote cria o repositório Git (se ainda não existir) e mostra a barra lateral de versionamento (Ctrl+Shift+G).

No modo automático, o LightNote salva versões (commits) sozinho nos momentos escolhidos nas Configurações Gerais (ao salvar, ao fechar a aba ou ao fechar a janela). Durante a sessão, entra no commit só o que o LightNote gravou — o que uma CLI de IA ou outro programa mudou fica pendente, para quem mudou fazer o próprio commit; o Ctrl+S salva a versão na hora, e o que o auto-salvar grava entra num commit a cada 10 minutos. Ao fechar a janela (ligado por padrão), o commit leva tudo o que mudou na pasta, inclusive fora do LightNote: é a rede de segurança do fim da sessão. No modo manual, você escreve a mensagem e salva a versão no painel. O indicador na barra de status mostra o estado (sem alterações, X alterados…) e, ao ser clicado, abre o menu do Git (veja abaixo) — numa pasta ainda sem versionamento, abre a configuração do espaço em Integrações. Dá para ver o diff de cada arquivo e restaurar (descartar) mudanças não salvas.

A automação tem 3 níveis por pasta (em Configuração do Espaço de Trabalho): Manual (nada automático), Commit automático (salva versões sozinho, mas não sincroniza) e Tudo automático (commita e sincroniza — push após o commit + pull periódico; exige credenciais de Git sem prompt). O painel mostra uma linha de estado com ↑ a enviar / ↓ a receber em relação ao remoto, e o botão principal muda de commit para Sincronizar quando há versões a enviar — assim fica claro que, depois de salvar, ainda falta sincronizar.

No painel e no menu Git da árvore há Adicionar (git add) e Restaurar (git restore) por arquivo, e um único Ver o que mudou, que abre a tela de comparação. A lista do painel segue a ordem natural dos caminhos, e o menu de contexto de um arquivo traz também Copiar... e Mostrar no Explorer (desabilitado para um arquivo apagado).

A tela de comparação mostra as duas versões lado a lado, alinhadas: os trechos iguais ficam sempre frente a frente e cada lado mostra o número de linha do seu arquivo. Uma linha trocada aparece em âmbar, com o pedaço que mudou realçado dentro dela. O botão Modo unificado troca para o formato de patch, Inverter os lados troca a base da comparação e F8 / Shift+F8 pulam de alteração em alteração.

O menu do Git na barra de status. Com a pasta versionada, o indicador mostra o ramo e, ao lado, o que falta sincronizar (↓ a receber, ↑ a enviar); a bolinha fica verde com tudo salvo em versão, âmbar com alterações pendentes e vermelha com arquivos em conflito. Clicar abre um menu que começa pelo estado completo e oferece Salvar versão de tudo (commit)… — leva todas as alterações da pasta, inclusive as de outros programas; com a mensagem em branco, ela é automática —, Abrir o painel Git e, com um repositório remoto, Sincronizar (receber e enviar), Receber (pull com merge), Enviar (push) e Verificar o remoto (fetch). O Receber sempre mescla (merge) e nunca faz rebase, qualquer que seja a configuração do Git da máquina; se o merge der conflito, o envio não acontece e o menu passa a oferecer Desfazer o merge com conflito…. Em Ações automáticas você troca o nível de automação da pasta sem abrir a configuração. Em Avançado, Executar comando git… roda qualquer comando na pasta do repositório e mostra a saída — sem terminal, então um comando que pede digitação (editor de mensagem, senha no console) desiste em vez de esperar; para esses, use o terminal. Se o Git não estiver instalado, o clique abre o guia de instalação.

Mover e renomear. Quando você move ou renomeia um arquivo ou uma pasta pelo LightNote (arrastando na árvore, recortando e colando, renomeando), a versão leva as duas metades juntas e o Git registra uma renomeação. Entra só o que já era versionado; um arquivo novo dentro da pasta movida espera, como os outros. Segue a mesma regra do Ctrl+S: com o commit ao salvar desligado, o move espera o próximo commit. Os grandes ficam de fora — veja Arquivos grandes e os limites dos serviços.

Histórico e faixa de alterações

A barra do editor de código e da nota tem dois botões para as versões do arquivo. Salvar versão grava o arquivo e guarda esta versão: numa pasta versionada com Git ele faz um commit só deste arquivo — o que outro programa ou uma sessão de IA mudou nos outros arquivos fica de fora —, e fora de um repositório guarda um ponto no histórico local. Ele fica cinza, com o motivo na dica, quando nada mudou desde a última versão.

Versões abre a lista de versões do arquivo aberto (a mesma seção da barra lateral), e a seta dele traz Salvar versão com mensagem…, Ver o que mudou desde a última versão e Descartar as alterações desde a última versão…, que volta o arquivo à última versão, com ou sem Git — o texto descartado fica no histórico local, e o Ctrl+Z também o traz de volta. A lista reúne os commits e os salvamentos locais: o LightNote grava um a cada Ctrl+S e, com o auto-salvar, no máximo um a cada 10 minutos por arquivo, além do arquivo como ele estava antes da primeira gravação — então funciona também numa pasta que não é repositório. Cada linha traz o assunto, o autor, quando foi e quantas linhas entraram e saíram; a bolinha distingue um commit seu, um salvamento do próprio LightNote e um commit vindo de uma sessão de IA. Havendo alterações ainda não commitadas, elas são a primeira linha. Clicar numa versão mostra o que mudou nela; abrir a versão inteira, comparar com a atual e comparar duas versões marcadas ficam no botão direito.

Uma faixa colorida na margem marca as linhas alteradas desde a última versão — no editor de código e na nota, e ela acompanha o que você digita: some quando você desfaz de volta ao original, sem esperar o salvamento. A última versão é o último commit no momento em que você abriu o arquivo — sem Git, o arquivo como estava ao abrir. Salvar e o commit automático não a movem: as marcas ficam até você clicar em Salvar versão ou fechar a aba. Para desligá-la, use Exibir → Faixa de alterações; desligada ela não é só escondida — nada passa a ser calculado. Clicar na faixa mostra como o trecho estava, com Reverter este trecho (o Ctrl+Z desfaz), Copiar original e Ver no diff, que abre a comparação completa já posicionada naquela linha. Quando o arquivo aberto muda fora do LightNote — uma CLI de IA gravando nele, por exemplo —, a aba sem alterações pendentes é recarregada em silêncio, e a faixa mostra o que mudou; com alterações suas em outros trechos, as duas são mescladas (o Ctrl+Z desfaz); e se as duas mexeram nas mesmas linhas, uma faixa amarela no topo da aba oferece Comparar, Ficar com a do disco e Manter a minha — até você escolher, o auto-salvar não grava aquele arquivo, e a versão que sai fica no histórico local. Uma ressalva sobre o histórico local: ele é guardado por caminho, então renomear o arquivo perde os salvamentos locais dele — os commits do Git, não.

Autoria da linha e troca de ramo

Quem escreveu esta linha. No menu do Git da barra de status, Autoria da linha (blame) põe, no fim da linha do cursor, quem a escreveu, quando e o resumo da versão — por exemplo Ana · há 3 dias · corrige o total. Só a linha do cursor é anotada, e a anotação acompanha o cursor. Uma linha que ainda não entrou em nenhuma versão diz Não versionado; com alterações não salvas, a anotação pede Salve para ver a autoria, porque as linhas do arquivo em disco já não casam com as da tela.

Trocar de ramo. O mesmo menu tem o submenu Ramo: main (com o nome do ramo atual), que lista os ramos locais: o atual vem marcado, e o clique em outro faz a troca (git checkout). Criar ramo… pede o nome, confere antes de chamar o Git (sem espaços, sem .., sem começar com -) e cria o ramo a partir do atual, já trabalhando nele. A troca fica desabilitada enquanto houver arquivo em conflito ou uma sincronização em andamento.

Backup e sincronização: o GitHub passo a passo

O link Fazer backup e sincronizar… do painel — o mesmo de Adicionar repositório remoto…, no menu ⋯ do painel e no menu do Git da barra de status — abre a tela Backup e sincronização, com três caminhos: o GitHub, que é o recomendado; Outro serviço; e uma Pasta sincronizada (OneDrive, Google Drive, Dropbox, pendrive ou rede). Todos funcionam; o GitHub é o mais simples para usar as notas em vários computadores e o mais seguro como backup. Para ele:

1. Crie a conta em github.com/signup: e-mail, senha e um nome de usuário; o GitHub manda um código para confirmar o e-mail. O plano Free basta.
2. Crie um repositório em github.com/new: dê um nome (por exemplo notas), marque Private e não marque Add a README, .gitignore nem licença. Ele precisa nascer vazio: com um README, o primeiro envio é recusado, porque o GitHub já teria uma história que não é a sua.
3. Copie o endereço HTTPS que a página mostra (algo como https://github.com/voce/notas.git) e cole em Endereço do repositório, na tela do LightNote. Deixe marcado Enviar as versões agora e clique em Conectar.
4. Entre na conta: no primeiro envio, o Git abre uma janela do GitHub para você autorizar pelo navegador. Depois disso o Windows guarda o acesso — quem guarda é o Git Credential Manager, que vem com o Git para Windows — e você não precisa entrar de novo.
5. No outro computador, instale o Git e o LightNote e use Arquivo → Clonar repositório Git... com o mesmo endereço. Daí em diante, Sincronizar recebe o que o outro computador enviou e envia o que você fez aqui.

Para não precisar lembrar de sincronizar, escolha Tudo automático na configuração da pasta: o LightNote envia depois de cada commit e recebe de tempos em tempos. Dois limites que vale conhecer: o GitHub recusa arquivos acima de 100 MB e recomenda repositórios de até cerca de 1 GB — guarde vídeos e arquivos grandes fora da pasta versionada. E privado quer dizer que só você (e quem você convidar) vê o repositório, mas o conteúdo fica nos servidores do GitHub: para o que é sigiloso, use o Markdown Seguro, que é cifrado antes de sair do computador.

No celular. Com o remoto ligado, Abrir no celular… (no menu ⋯ do painel e no menu do Git da barra de status) mostra um QR code. No LightNote do celular, toque no nome do espaço e escolha Ler o QR code do computador: o repositório vira um espaço novo no celular. O QR leva só o endereço, nunca a senha — se o repositório for privado, o celular usa a conta Git que tiver para o servidor, ou pede um token de acesso. O celular clona por HTTPS: um remoto que é uma pasta deste computador (o OneDrive, abaixo) não chega a ele.

Arquivos grandes e os limites dos serviços

Os limites. O GitHub avisa a partir de 50 MB por arquivo e recusa arquivos acima de 100 MB; o GitLab, o Bitbucket e o Azure Repos também recusam acima de 100 MB. Para o repositório inteiro, o GitHub recomenda até cerca de 1 GB (no máximo 5 GB), e o plano gratuito do Bitbucket dá 1 GB. Uma pasta sincronizada (OneDrive, Google Drive) não tem esse teto.

Por que o cuidado é no commit. O limite vale para toda versão do histórico, não só para os arquivos de hoje: se um arquivo de 120 MB entra numa versão, o envio é recusado — e continua recusado depois de você apagar o arquivo, porque a versão antiga ainda o contém.

O que o LightNote faz. Arquivo acima de 100 MB fica fora de toda versão que o app salva — o commit automático, o Ctrl+S, o Salvar versão, o commit ao fechar a janela, o snapshot e a sincronização do celular. Ele continua na pasta, e um aviso oferece Ignorar no Git (.gitignore). Acima de 50 MB o arquivo entra, com um aviso na barra de status. Arquivo marcado para o Git LFS (que guarda só um ponteiro no repositório) não é segurado.

Se o envio já foi recusado (a versão foi salva fora do LightNote, num terminal), o painel do Git diz isso. Apagar o arquivo não resolve. Se a versão ainda não foi enviada, rode reset @{u} em Avançado → Executar comando git… do menu do Git da barra de status: as versões não enviadas são desfeitas e os arquivos ficam como estão; ponha o arquivo grande no .gitignore e salve a versão de novo. Para guardar o arquivo no repositório, use o Git LFS (git-lfs.com).

Outros serviços, OneDrive/Google Drive e servidor próprio

Outros serviços. O Git funciona do mesmo jeito com qualquer serviço; muda só o lugar onde você cria o repositório. Os mais conhecidos: o GitLab (gitlab.com, grátis, com repositórios privados de até 10 GB cada), o Bitbucket (bitbucket.org, grátis até 5 usuários, com 1 GB no total), o Azure DevOps (dev.azure.com, da Microsoft, grátis até 5 usuários e com repositórios privados ilimitados) e o Codeberg (codeberg.org, sem fins lucrativos, mas só para projetos de código aberto — não serve para notas privadas). Crie lá um repositório vazio e privado, copie o endereço e escolha Outro serviço na tela Backup e sincronização. Os limites dos planos mudam com o tempo: confira no site de cada um.

OneDrive, Google Drive ou Dropbox, sem conta nova. Escolha Pasta sincronizada e aponte a pasta do serviço neste computador (por exemplo C:\Users\voce\OneDrive ou G:\Meu Drive). O LightNote cria lá dentro um repositório bare — uma pasta Notas.git que guarda só as versões, sem os arquivos de trabalho — e passa a usá-lo como remoto; o serviço de nuvem se encarrega de copiar essa pasta. No outro computador, espere a pasta aparecer sincronizada e use Arquivo → Clonar repositório Git..., colando o caminho dela. A mesma opção serve para um pendrive ou uma pasta de rede, como backup.

• Por que um bare, e não a pasta de notas inteira dentro do OneDrive? A pasta .git muda o tempo todo enquanto você trabalha, e dois computadores sincronizando-a pela nuvem podem corrompê-la. No bare, só o envio escreve, e o que ele grava não muda depois.
• Um computador por vez. Antes de trabalhar no outro computador, espere o OneDrive ou o Drive terminar de sincronizar; enviar dos dois lados antes disso pode criar cópias em conflito. Se isso acontecer com frequência, o GitHub é a saída mais tranquila.
• Se a pasta de trabalho já está na nuvem — o Windows costuma pôr a pasta Documentos no OneDrive —, a tela avisa. Num computador só, o OneDrive faz o papel de backup; para usar as notas em vários, prefira o GitHub ou tire a pasta de notas da nuvem e deixe lá só o bare.
• Sem Git também dá: sincronize a pasta de notas inteira pelo serviço de nuvem e deixe o versionamento desligado — o histórico local continua guardando as versões de cada arquivo. É o caminho de Suas notas no celular.

Um servidor seu. Para não depender de empresa nenhuma, dá para hospedar o próprio servidor Git. O Gitea e o Forgejo são leves, têm uma interface web parecida com a do GitHub e rodam em Docker — num computador de casa, num Raspberry Pi, num NAS ou numa VPS alugada. O mais simples de todos é um servidor com SSH e um repositório criado com git init --bare. O preço é cuidar do servidor: instalar, atualizar e fazer o backup dele; os guias de instalação estão no site de cada projeto. Pronto o servidor, o endereço do repositório vai em Outro serviço, como qualquer outro.