7  Configurando o Git e o GitHub

No capítulo anterior, você conheceu a história do Git e do GitHub, entendeu o que é controle de versão e por que essas ferramentas se tornaram essenciais. Agora é hora de colocar a mão na massa: vamos configurar tudo no seu computador para que você possa começar a versionar seus projetos.

Mas antes de começar, é importante ter algo para versionar. Não faz sentido enviar uma pasta vazia para o GitHub — o controle de versão existe justamente para acompanhar a evolução de arquivos reais. Portanto, certifique-se de ter um projeto com pelo menos alguns arquivos antes de seguir os passos deste capítulo. Pode ser um trabalho acadêmico, uma análise de dados, anotações de estudo, ou qualquer outro material que você queira manter organizado e seguro.

Se você pretende publicar seu projeto como uma página na internet usando o GitHub Pages (que veremos em um capítulo adiante), vale a pena considerar o uso de arquivos no formato Quarto (extensão .qmd). O Quarto é um sistema de publicação científica que permite escrever texto, código e resultados em um único documento. Ferramentas como o Positron e o RStudio conseguem renderizar esses arquivos — ou seja, transformá-los em documentos finais como HTML, PDF ou Word.

O processo de renderização é especialmente interessante para quem quer criar sites: quando você renderiza um projeto Quarto configurado como site ou livro, ele gera uma pasta (geralmente chamada docs ou _site) contendo arquivos HTML prontos para a web. É essa pasta que o GitHub Pages consegue ler e transformar em um site público acessível por qualquer pessoa. Assim, o fluxo completo seria: você escreve em Quarto, renderiza para HTML, envia para o GitHub, e ativa o GitHub Pages — pronto, seu material está online.

Por enquanto, não se preocupe com os detalhes do Quarto ou do GitHub Pages. Neste capítulo, vamos focar no essencial: criar sua conta no GitHub, instalar e configurar o Git, e aprender o fluxo básico de trabalho — da criação de um repositório local até o envio para a nuvem.

7.1 Verificando se o Git já está instalado

Antes de instalar o Git, verifique se ele já está no seu computador. Abra o Terminal e digite:

git --version

Se o Git estiver instalado, você verá uma mensagem indicando a versão:

git version 2.50.1

Se aparecer uma versão, ótimo — você pode pular para a seção de configuração. Se não estiver instalado, siga as instruções da próxima seção.

7.2 Instalando o Git

A forma mais prática de instalar o Git é usando os gerenciadores de pacotes que você aprendeu nos capítulos anteriores.

No Mac (com Homebrew):

brew install git

No Windows (com winget):

winget install Git.Git

Após a instalação, feche e reabra o Terminal, então confirme que funcionou:

git --version
NotaAlternativas de instalação
  • Mac: se você não usa Homebrew, ao digitar git --version o sistema oferecerá automaticamente a instalação das Command Line Tools da Apple, que incluem o Git.
  • Windows: se preferir não usar o winget, baixe o instalador em git-scm.com. Durante a instalação, mantenha as opções padrão. O instalador incluirá o Git Bash, que permite usar comandos no estilo Unix.
  • Linux: use o gerenciador de pacotes da sua distribuição. No Ubuntu/Debian: sudo apt install git

7.3 Configuração inicial

Com o Git instalado, configure sua identidade. Essas informações aparecerão em cada commit que você fizer:

git config --global user.name "Seu Nome"
git config --global user.email "seu.email@exemplo.com"

Use o mesmo e-mail da sua conta GitHub. Isso permite que o GitHub associe seus commits ao seu perfil.

DicaVerificando a configuração

Para verificar se está tudo configurado corretamente:

git config --global user.name
git config --global user.email

Se retornar seu nome e e-mail, está tudo certo!

Você também pode ver todas as configurações do Git com:

git config --list

7.4 Conceitos fundamentais

Antes de partir para os comandos, é importante entender três “lugares” onde seus arquivos podem estar:

  1. Diretório de trabalho (working directory): sua pasta normal, onde você edita arquivos
  2. Área de preparação (staging area): uma área intermediária onde você seleciona quais alterações quer registrar
  3. Repositório (repository): o histórico completo de todas as versões salvas

O fluxo básico é: você edita arquivos → adiciona à área de preparação → confirma (commit) no repositório → envia (push) para o GitHub.

flowchart LR
    A[Diretório de Trabalho] -->|git add| B[Área de Preparação]
    B -->|git commit| C[Repositório Local]
    C -->|git push| D[GitHub]

7.5 Subindo uma pasta para o GitHub: passo a passo

Vamos ao processo completo de versionar uma pasta local e enviá-la para o GitHub. Primeiro, claro, escolha uma pasta no seu computador para usar nesse passo. É importante ter algum arquivo nessa pasta, pois vamos subir os arquivos dessa pasta para o github. Crie ou escolha uma pasta e vamos começar.

7.5.1 Passo 1: Crie um repositório no GitHub

Acesse github.com, faça login e clique no botão + no canto superior direito, depois em New repository. Dê um nome ao repositório (por exemplo, meu-projeto), escolha se será público ou privado, e clique em Create repository.

AvisoRepositório vazio

Não marque nenhuma opção de inicialização (README, .gitignore, etc.) — queremos um repositório vazio para este exemplo.

7.5.2 Passo 2: Navegue até sua pasta no Terminal

Usando o terminal, vá para a pasta em seu computador que pretende subir para o GitHub. Todas as açoes do git devem acontecer com você dentro da pasta que pretende subir, usando o Terminal.

cd ~/caminho/para/sua/pasta

Por exemplo, se sua pasta se chama teste e está na área de trabalho:

cd ~/Desktop/teste

7.5.3 Passo 3: Inicialize o Git na pasta

git init

Isso cria uma pasta oculta .git que armazenará todo o histórico. Sua pasta agora é um repositório Git local.

7.5.4 Passo 4: Adicione os arquivos à área de preparação

Antes de continuar, é importante entender que essa etapa e os próximos passos ainda acontecem apenas no seu computador. Nada será enviado para o GitHub até o Passo 7. O Git trabalha com três áreas locais:

Diretório de trabalho — sua pasta normal, onde você edita arquivos Área de preparação (staging area) — onde você seleciona quais alterações farão parte do próximo commit Repositório local — onde o Git armazena o histórico de commits

Nesse passo 4 estamos apenas movendo os arquivos para área de preparação, no seu diretório local, em sua pasta em seu computador.

O comando git add move arquivos do diretório de trabalho para a área de preparação. É como colocar itens em uma caixa antes de lacrar — você está dizendo ao Git: “esses arquivos devem ser incluídos no próximo registro”.

git add .

O ponto (.) significa “todos os arquivos”. Se quiser adicionar apenas um arquivo específico:

git add nome-do-arquivo.txt

Neste momento, seus arquivos não foram registrados no histórico e continuam apenas no seu computador, estão na área de preparação, aguardando o commit.

7.5.5 Passo 5: Faça o primeiro commit

O comando git commit pega tudo que está na área de preparação e cria um registro permanente no histórico do repositório local. Pense no commit como lacrar a caixa e colocar uma etiqueta descrevendo o conteúdo.

git commit -m "Primeiro commit"

A flag -m permite adicionar uma mensagem de commit — um texto curto que descreve o que foi alterado. Essa mensagem é obrigatória: o Git não permite criar um commit sem ela. O motivo é simples: quando você olhar o histórico do projeto semanas ou meses depois, essas mensagens serão seu guia para entender o que aconteceu em cada momento. Uma mensagem como “Adiciona análise exploratória dos dados” ou “Corrige erro no cálculo de médias” é muito mais útil do que “Alterações” ou “Atualização”. Pense na mensagem de commit como uma anotação para o seu eu do futuro — seja gentil com ele e escreva algo que faça sentido.

Após o commit, seus arquivos estão registrados no repositório Git local. Eles ainda estão apenas no seu computador — seguros no histórico do Git, mas não na nuvem. Se seu computador tiver um problema agora, você ainda perderia tudo. O envio para o GitHub acontece apenas nos próximos passos.

7.5.6 Passo 6: Conecte ao repositório remoto

Até agora, tudo aconteceu apenas no seu computador. Você tem um repositório Git local com um commit registrado, mas ele não tem nenhuma relação com o repositório que você criou no GitHub lá no Passo 1. São dois repositórios independentes que ainda não se conhecem.

Para que eles possam se comunicar, precisamos criar uma conexão chamada remote. Um remote é um apelido que aponta para a URL de um repositório remoto. Em vez de digitar a URL completa toda vez que quiser enviar ou baixar alterações, você usa esse apelido.

Neste passo, você vai precisar de duas informações que definiu anteriormente: o nome de usuário que escolheu ao criar sua conta no GitHub e o nome do repositório que criou no Passo 1. Essas duas informações formam a URL do seu repositório, que segue sempre o mesmo padrão: https://github.com/nome-de-usuario/nome-do-repositorio.git. Se você não lembra o nome exato, basta acessar o GitHub no navegador — o nome de usuário aparece no canto superior direito, e o nome do repositório está na lista de repositórios da sua conta.

O comando para fazer essa integração é esse:

git remote add origin https://github.com/seu-usuario/meu-projeto.git

Substitua seu-usuario pelo seu nome de usuário do GitHub e meu-projeto pelo nome do repositório que você criou.

Vamos entender cada parte desse comando:

git remote add — instrução para adicionar um novo remote origin — o apelido que estamos dando ao repositório remoto. Esse nome é uma convenção universalmente adotada para o remote principal, mas você poderia usar qualquer nome https://github.com/...— a URL do repositório no GitHub

Para confirmar que a conexão foi estabelecida, use:

git remote -v

Você verá algo como:

origin  https://github.com/seu-usuario/meu-projeto.git (fetch)
origin  https://github.com/seu-usuario/meu-projeto.git (push)

Essas duas linhas indicam que o remote origin está configurado tanto para baixar alterações (fetch) quanto para enviar (push). Agora seu repositório local sabe para onde enviar os commits. Nada foi enviado ainda — falta apenas dar o comando de envio.

7.5.7 Passo 7: Envie para o GitHub

Finalmente chegou o momento em que seus arquivos vão sair do seu computador e viajar para a nuvem. Até agora, você inicializou o Git na pasta, adicionou os arquivos à área de preparação, criou um commit com uma mensagem descritiva e estabeleceu a conexão com o repositório remoto. Tudo isso aconteceu localmente, sem nenhuma comunicação com a internet. O comando push é o que efetivamente transfere seus commits para o GitHub, tornando-os acessíveis de qualquer lugar e protegidos contra problemas no seu computador.

git push -u origin main

Vamos entender cada parte desse comando:

git push — instrução para enviar commits para o repositório remoto.
-u (ou –set-upstream) — cria uma conexão permanente entre sua branch local e a branch remota. Isso permite que, nas próximas vezes, você use apenas git push sem precisar especificar o destino.
origin — o apelido do remote que criamos no passo anterior.
main — o nome da branch que estamos enviando.

Na primeira vez que você executa esse comando, o Git pode pedir suas credenciais do GitHub. Dependendo do seu sistema, pode abrir uma janela de autenticação no navegador ou pedir usuário e senha diretamente no Terminal. Após autenticar, o envio será realizado.

Se tudo der certo, você verá uma mensagem indicando que os arquivos foram enviados. Agora abra o navegador, acesse seu repositório no GitHub e atualize a página — seus arquivos estarão lá, junto com a mensagem do commit que você escreveu. Parabéns! Você acabou de completar o ciclo básico do Git: inicializar, preparar, commitar, conectar e enviar. A partir de agora, sempre que fizer alterações no projeto, o fluxo será mais simples:

git add .
git commit -m "Descrição das alterações"
git push
NotaBranch main vs master

Se o Git reclamar que a branch se chama master em vez de main, use:

git branch -M main
git push -u origin main

7.6 Comandos do dia a dia

Depois que tudo estiver configurado, seu fluxo de trabalho será:

# Ver o status dos arquivos
git status

# Adicionar alterações
git add .

# Confirmar alterações com uma mensagem
git commit -m "Descrição do que você fez"

# Enviar para o GitHub
git push

7.7 Outros comandos úteis

7.7.1 Histórico

# Ver o histórico de commits
git log

# Ver histórico resumido (uma linha por commit)
git log --oneline

7.7.2 Sincronização

# Baixar alterações do GitHub para seu computador
git pull

# Clonar um repositório existente do GitHub
git clone https://github.com/usuario/repositorio.git

# Ver quais repositórios remotos estão conectados
git remote -v

7.7.3 Desfazendo alterações

# Desfazer alterações em um arquivo (voltar à última versão commitada)
git checkout -- nome-do-arquivo.txt

# Remover um arquivo da área de preparação (mas manter as alterações)
git reset nome-do-arquivo.txt

7.8 Autenticação no GitHub

Na primeira vez que você tentar fazer push, o GitHub pedirá autenticação. Há duas formas principais:

7.8.1 Opção 1: Token de acesso pessoal (HTTPS)

  1. Acesse GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token
  2. Selecione os escopos necessários (pelo menos repo)
  3. Copie o token gerado
  4. Use-o como senha quando o Terminal pedir

7.8.2 Opção 2: Chave SSH (recomendada para uso frequente)

Essa opção é mais segura e prática para quem usa Git diariamente, mas a configuração é mais complexa. Ela será tratada em um capítulo à parte.

7.9 Arquivos ocultos

Antes de falarmos sobre o próximo tópicos, sobre o arquivo .gitignore, precisamos entender um conceito importante: arquivos ocultos.

Você já deve ter notado que alguns arquivos e pastas no seu computador parecem “invisíveis” — eles existem, mas não aparecem quando você abre uma pasta no Finder (Mac) ou no Explorador de Arquivos (Windows). Esses são os arquivos ocultos.

7.9.1 Por que existem arquivos ocultos?

Sistemas operacionais e programas criam arquivos de configuração, caches e dados internos que o usuário comum não precisa ver no dia a dia. Para evitar confusão e impedir que esses arquivos sejam deletados acidentalmente, eles ficam escondidos por padrão.

No Mac e no Linux, a convenção é simples: qualquer arquivo ou pasta cujo nome começa com um ponto (.) é considerado oculto. Por exemplo:

  • .gitignore — arquivo de configuração do Git
  • .git/ — pasta onde o Git armazena todo o histórico do repositório
  • .DS_Store — arquivo que o macOS cria automaticamente em cada pasta
  • .Rhistory — histórico de comandos do R

No Windows, arquivos ocultos são marcados através de um atributo especial do sistema, não necessariamente pelo nome.

7.9.2 Por que isso importa para o Git?

O Git usa arquivos ocultos extensivamente. Quando você executa git init em uma pasta, ele cria uma pasta oculta chamada .git que contém todo o histórico, configurações e metadados do repositório. Se você não souber visualizar arquivos ocultos, vai parecer que nada aconteceu.

Além disso, o arquivo .gitignore — que ensinaremos a criar na próxima seção — também é oculto. Se você criá-lo mas não conseguir vê-lo, pode ficar confuso achando que algo deu errado.

Por isso, saber visualizar arquivos ocultos é uma habilidade fundamental para trabalhar com Git.

7.9.3 Como visualizar arquivos ocultos

No Mac (Finder):

Pressione Cmd + Shift + . (ponto). Os arquivos ocultos aparecerão com um tom mais claro, indicando que normalmente são invisíveis. Pressione a mesma combinação novamente para escondê-los.

No Windows (Explorador de Arquivos):

  1. Abra o Explorador de Arquivos
  2. Clique na aba Exibir
  3. Marque a caixa Itens ocultos

No Terminal (Mac, Linux e Git Bash no Windows):

O comando ls lista arquivos, mas por padrão não mostra os ocultos. Para ver todos os arquivos, incluindo os ocultos, use a flag -a:

ls -a

Para uma listagem detalhada com arquivos ocultos:

ls -la

Você verá arquivos como .git, .gitignore e .DS_Store que normalmente não aparecem.

DicaExperimente agora

Navegue até uma pasta onde você já executou git init e use ls -la no Terminal. Você verá a pasta .git que antes parecia não existir. Ou ative a visualização de arquivos ocultos no Finder/Explorador e observe quantos arquivos “secretos” existem nas suas pastas.

7.10 O arquivo .gitignore

Agora que você sabe o que são arquivos ocultos e como visualizá-los, podemos falar sobre um dos arquivos ocultos mais importantes para o Git: o .gitignore.

7.10.1 O problema: nem tudo deve ir para o repositório

Quando você executa git add . para adicionar arquivos ao repositório, o Git inclui tudo o que encontrar na pasta — e nem sempre isso é desejável. Alguns arquivos são grandes demais e tornariam o repositório pesado e lento de clonar. Outros contêm informações sensíveis, como senhas ou dados pessoais, que jamais deveriam ser compartilhados. Há ainda arquivos temporários que o sistema operacional ou programas criam automaticamente e que não têm utilidade para outras pessoas.

Imagine que você está trabalhando em um projeto de análise de dados. Sua pasta contém:

  • Seus scripts em R ou Python — devem ir para o GitHub
  • Um arquivo CSV com 500MB de dados brutos — não deveria ir, é grande demais e pode conter dados sensíveis
  • Um arquivo com senhas de banco de dados — definitivamente não deveria ir!
  • Arquivos .DS_Store que o macOS cria automaticamente — não têm utilidade para outras pessoas

Sem o .gitignore, toda vez que você executar git add ., todos esses arquivos seriam incluídos. O .gitignore resolve isso: ele diz ao Git quais arquivos e pastas devem ser completamente ignorados.

7.10.2 Criando o arquivo .gitignore

O .gitignore deve ficar na raiz do seu projeto (na mesma pasta onde está a pasta .git). Para criá-lo, você pode usar o Terminal:

touch .gitignore

Ou criar diretamente no seu editor de código. Como o nome começa com ponto, o arquivo será oculto — lembre-se de ativar a visualização de arquivos ocultos se quiser vê-lo no Finder ou Explorador.

O .gitignore é um arquivo de texto simples. Cada linha representa um padrão de arquivos ou pastas que o Git deve ignorar.

7.10.3 Sintaxe do .gitignore

A sintaxe é simples, mas poderosa:

Ignorar um arquivo específico:

senhas.txt
dados_secretos.csv

Ignorar todos os arquivos com determinada extensão:

*.csv
*.xlsx
*.log

O asterisco (*) funciona como curinga, significando “qualquer coisa”.

Ignorar uma pasta inteira:

node_modules/
dados/
.Rproj.user/

A barra (/) no final indica que é uma pasta. Tudo dentro dela será ignorado.

Ignorar arquivos em qualquer subpasta:

**/*.log

O duplo asterisco (**) significa “em qualquer nível de subpastas”.

Adicionar comentários:

# Arquivos temporários do macOS
.DS_Store

# Dados que não devem ser compartilhados
*.csv

Linhas que começam com # são comentários e ajudam a organizar o arquivo.

Fazer exceções (não ignorar algo específico):

# Ignora todos os CSVs
*.csv

# Mas não ignora este arquivo específico
!exemplo_dados.csv

O ponto de exclamação (!) no início nega a regra anterior.

7.10.4 Exemplo completo de .gitignore

Aqui está um exemplo típico para projetos em R ou análise de dados:

# === Sistema Operacional ===

# Arquivos temporários do macOS
.DS_Store

# Arquivos temporários do Windows
Thumbs.db
desktop.ini

# === R e RStudio ===

# Arquivos de sessão do R
.Rhistory
.RData
.Rproj.user/

# === Dados ===

# Arquivos de dados (geralmente grandes ou sensíveis)
*.csv
*.xlsx
*.sav
*.dta
dados/

# === Credenciais e segredos ===

# Nunca suba senhas ou tokens!
.env
senhas.txt
*_secret*

# === Arquivos temporários e de build ===

# Pastas geradas automaticamente
_site/
docs/
node_modules/

# Arquivos de cache
*.cache
__pycache__/

7.10.5 Quando criar o .gitignore

O ideal é criar o .gitignore logo no início do projeto, antes do primeiro commit. Assim, os arquivos indesejados nunca chegam a entrar no histórico do Git.

Se você já fez commit de arquivos que deveriam ser ignorados, adicioná-los ao .gitignore depois não os remove do histórico — apenas impede que futuras alterações sejam rastreadas. Para remover um arquivo que já está no repositório mas deveria ser ignorado:

git rm --cached nome-do-arquivo.csv
git commit -m "Remove arquivo que deveria ser ignorado"

A flag --cached remove o arquivo do Git mas mantém ele na sua pasta local.

DicaModelos prontos de .gitignore

Não precisa criar tudo do zero. O GitHub mantém uma coleção de modelos de .gitignore para diversas linguagens e ambientes em github.com/github/gitignore.

Lá você encontra modelos para R, Python, Node.js e dezenas de outras tecnologias. É só copiar o conteúdo relevante para o seu projeto.

Outra opção é o site gitignore.io, onde você digita as tecnologias que usa (ex: “R, macOS, Windows”) e ele gera um .gitignore personalizado.

AvisoArquivos sensíveis

Nunca suba senhas, tokens de API, chaves de acesso ou dados pessoais para o GitHub — mesmo em repositórios privados. Uma vez que algo entra no histórico do Git, é difícil remover completamente. Sempre use .gitignore para proteger esses arquivos desde o início.

DicaModelos de .gitignore

O GitHub mantém uma coleção de modelos de .gitignore para diversas linguagens e ambientes em github.com/github/gitignore. Vale consultar o modelo para R, Python ou a linguagem que você usa.

7.11 Dicas finais

DicaBoas práticas

  1. Faça commits pequenos e frequentes. É mais fácil entender o histórico e reverter problemas.

  2. Escreva mensagens de commit descritivas. “Corrige bug no cálculo de médias” é melhor que “Alterações”.

  3. Use .gitignore desde o início. Evite subir arquivos desnecessários ou sensíveis.

  4. Não tenha medo de errar. O Git foi feito justamente para permitir que você experimente e volte atrás se necessário.