Repositório Git: como criar com git init e conectar um remote

Um repositório Git é um projeto cujas alterações são acompanhadas pelo Git. Fisicamente, é uma pasta comum com os seus arquivos, mais o diretório oculto .git, onde fica todo o histórico: commits, branches, tags, configurações. Apague o .git e sobram só os arquivos, sem nenhuma versão anterior.

Do que um repositório é feito

Ao trabalhar com Git, ajuda ter em mente três áreas por onde as alterações passam:

• diretório de trabalho (working tree) — os arquivos que você vê e edita;
• índice (staging area) — o rascunho do próximo commit, para onde as alterações vão com git add;
• histórico — o banco de commits dentro do .git, para onde as alterações vão com git commit.

A rigor, o repositório em si é o conteúdo do .git. O diretório de trabalho é apenas uma versão "desempacotada" do projeto que o Git tira do histórico.

Como criar um repositório Git com git init

Entre na pasta do projeto e rode um único comando:

cd ~/projects/my-app
git init

Initialized empty Git repository in /home/user/projects/my-app/.git/

Você pode criar o repositório numa pasta vazia ou numa pasta que já tem arquivos. No segundo caso nada se perde: os arquivos existentes só ficam como não rastreados (untracked) até você adicioná-los com git add.

Variações úteis do comando:

# Criar a pasta e o repositório dentro dela de uma vez
git init my-app

# Definir o nome da primeira branch (senão: master ou o valor das configurações)
git init -b main

# Tornar main a branch padrão de todos os repositórios novos
git config --global init.defaultBranch main

O primeiro commit

Um repositório vazio, sem commits, quase não serve para nada. Logo depois do git init, normalmente se faz isto:

git config --global user.name "João Silva"
git config --global user.email "joao@example.com"

git status
git add .
git commit -m "Estrutura inicial do projeto"

Nome e e-mail são configurados uma vez por computador — eles vão gravados em cada commit. Sem eles, o Git se recusa a commitar e pede que você se identifique.

Adicione o .gitignore logo de cara

Antes do primeiro git add ., crie o arquivo .gitignore com a lista do que não deve entrar no repositório: dependências, builds, segredos, arquivos da IDE.

node_modules/
dist/
.env
.idea/
.vscode/
*.log
__pycache__/

Se o arquivo já entrou num commit, o .gitignore não o remove. É preciso deixar de rastreá-lo, mantendo-o no disco: git rm --cached .env, e depois commitar.

O que tem dentro da pasta .git

No dia a dia não é preciso mexer ali, mas entender a estrutura tira muitas dúvidas:

Daí uma conclusão importante: uma branch no Git é um arquivinho com um único hash. Por isso criar branches é instantâneo e não custa nada.

Como verificar se uma pasta é um repositório

git status
# ou, de forma mais precisa
git rev-parse --is-inside-work-tree

Fora de um repositório, você recebe fatal: not a git repository (or any of the parent directories): .git. Repare no "parent directories": o Git procura o .git subindo pela árvore de pastas. Se você rodar git init sem querer no seu diretório home, ele inteiro vira um repositório — essa pasta .git precisa ser apagada.

Repositório local e remoto

O repositório criado com git init existe só no seu computador. Para compartilhar o código e ter um backup, conecta-se a ele um repositório remoto (remote) — uma cópia num servidor: GitHub, GitLab, Bitbucket ou um servidor Git próprio.

Para o Git, o repositório remoto não é o "principal": cada cópia é completa e contém todo o histórico. O que o torna central é apenas o combinado do time.

git remote: conectando um repositório remoto

Um remote é um nome curto para o endereço do servidor. Por convenção, o nome principal é origin.

# Adicionar um remote
git remote add origin git@github.com:username/my-app.git

# Ver a lista com os endereços
git remote -v

origin  git@github.com:username/my-app.git (fetch)
origin  git@github.com:username/my-app.git (push)

Em seguida, envie a branch e ligue-a à remota:

git push -u origin main

Principais comandos git remote

Formatos de endereço

• https://github.com/user/repo.git — HTTPS, funciona em qualquer lugar; para escrever, precisa de token;
• git@github.com:user/repo.git — SSH, precisa de chave; depois de configurado, não pede senha;
• /srv/git/repo.git ou file:///srv/git/repo.git — caminho local, prático para experimentos.

Erros comuns

"error: remote origin already exists". Já existe um remote com esse nome. Se você quer trocar o endereço, use git remote set-url origin <url>, e não um novo add.

"failed to push some refs" / "Updates were rejected". O servidor tem commits que você não tem — muitas vezes é o README criado ao abrir o repositório no site. Rode git pull --rebase origin main e tente o push de novo. Se os históricos não tiverem nenhuma relação, o Git responde "refusing to merge unrelated histories" — aí o git pull precisa da flag --allow-unrelated-histories. É mais simples criar o repositório vazio no site.

"src refspec main does not match any". Você está tentando enviar uma branch que não existe: ou ainda não houve nenhum commit, ou a branch se chama master. Confira com git branch.

Seu próprio servidor Git: repositório bare

O GitHub não é obrigatório. Qualquer máquina à qual você tenha acesso SSH pode ser o repositório remoto. Para isso, cria-se no servidor um repositório "nu" (bare) — sem diretório de trabalho, só com o conteúdo do .git:

# No servidor
ssh user@server
git init --bare /srv/git/my-app.git

# No seu computador
git remote add origin user@server:/srv/git/my-app.git
git push -u origin main

Para três pessoas trabalharem com esse servidor, basta dar aos colegas acesso SSH à pasta do repositório e um grupo comum com permissão de escrita. Para controlar permissões por branch e por projeto isso já não basta — aí você precisa de uma hospedagem Git completa.

Num repositório bare não dá para "entrar e corrigir um arquivo" — ele serve só para troca via push e fetch. É exatamente assim que funcionam os repositórios em qualquer hospedagem Git. Se você precisa de interface web, review e issues, instale soluções self-hosted como GitLab, Gitea ou Forgejo.

Branches de rastreamento: como o repositório local enxerga o servidor

Depois de conectar o remote e fazer o primeiro git fetch ou git push, aparecem no repositório branches remotas como origin/main. Não são as branches do servidor, e sim "fotografias" locais do que você viu no servidor na última sincronização. Elas só são atualizadas com fetch, pull e push.

Daí a diferença importante entre os três comandos de troca:

Para saber quanto sua branch está atrás ou à frente:

git fetch
git status -sb

## main...origin/main [ahead 2, behind 1]

Aqui você tem dois commits que não estão no servidor, e o servidor tem um que você não tem. Antes do push, é preciso trazer esse commit.

A ligação entre a branch local e a remota (upstream) é definida com a flag -u no primeiro push. Se esqueceu, dá para configurar depois: git branch --set-upstream-to=origin/main. Para ver todas as ligações — git branch -vv.

Vários repositórios: monorepo ou um por projeto

Uma dúvida frequente de iniciantes é quantos repositórios Git criar. Regra simples: um repositório para cada unidade desenvolvida e lançada de forma independente. Projetos de estudo, projetos pessoais e serviços separados são repositórios diferentes. Não crie um único repositório para a pasta "Meus projetos" inteira: o histórico se mistura e fica difícil publicar um projeto sozinho no portfólio.

Grandes empresas às vezes mantêm todo o código num monorepo, por causa das mudanças transversais e do build unificado, mas essa é uma decisão de arquitetura consciente, com ferramentas próprias. Quem está começando deve seguir a regra "um projeto, um repositório" e nunca colocar um repositório dentro de outro sem submodules.

git init ou git clone

Depois do git clone, o remote origin já vem configurado; não é preciso adicioná-lo manualmente.

Passo a passo: da pasta ao repositório no GitHub

1. Crie a pasta do projeto e rode git init -b main.
2. Adicione o .gitignore e o README.
3. Faça o primeiro commit: git add . e git commit -m "Initial commit".
4. Crie no GitHub um repositório vazio — sem README, licença ou .gitignore.
5. Conecte-o: git remote add origin <endereco>.
6. Envie o código: git push -u origin main.
7. Daí em diante, trabalhe no ciclo: edições → git add → git commit → git push.

Conclusão

Um repositório Git é o seu projeto mais a pasta .git com o histórico completo. Ele é criado com git init, e a conexão com o servidor é configurada com git remote add origin e o primeiro git push -u. O repositório remoto pode ser o GitHub, o GitLab ou o seu próprio servidor Git com um repositório bare. A criação do primeiro repositório, o índice e a conexão do remote são praticados no curso de Git.