Como inicializar um repositório Git com git init

Resposta rápida: execute git init no diretório de um projeto para criar um repositório Git local. O comando cria um diretório oculto .git/, mas não prepara arquivos, cria um commit, cria um repositório no GitHub nem envia nada.

Padrões usados nesta página: a saída exibida vem de um repositório que usa o formato de objetos SHA-1 padrão do Git e o back-end de referências padrão files; por isso, você vê .git/objects/ e .git/refs/heads/. git init --object-format=sha256 e git init --ref-format=reftable alteram esses dois detalhes sem mudar o layout geral descrito aqui.

Sintaxe

git init                  # initialise the current directory
git init <directory>      # create the directory, then initialise it
git init --bare <dir>     # create a repository with no working tree
git init -b main          # set the initial branch name

Como inicializar um repositório Git

Para um projeto novo, crie uma pasta, inicialize-a e depois prepare e registre um arquivo:

mkdir my-project
cd my-project
git init -b main
echo "# My project" > README.md
git add README.md
git commit -m "Initial commit"

Se você já tem um projeto, rode git init a partir da raiz dele em vez de criar uma pasta nova. git init -b main define o nome do branch inicial nas versões do Git que oferecem suporte; o git init sem opções usa o padrão configurado. O Git não rastreia arquivos até você prepará-los com git add e registrar um commit com git commit. Se o Git pedir seus dados de autor, siga o guia de git config. Para publicar o repositório depois, adicione um remoto com git remote e faça o push separadamente.

Quando executado em uma pasta de projeto existente, o git init cria ou atualiza os metadados do repositório em .git/; ele não prepara nem faz commit dos arquivos do projeto. git init <directory> também cria o diretório de destino se ele não existir, e reinicializar um repositório pode atualizar metadados ou modelos de hooks. A partir daí, a sequência normal é git add para preparar os arquivos e git commit para registrar o primeiro snapshot.

O que git init realmente faz?

Em essência, o sistema de arquivos de um computador é relativamente simples: ele acompanha nomes de arquivos, conteúdo, tamanhos e hierarquias de diretórios. Ele não entende nativamente histórico de alterações, identidades de autores ou ramificações.

Quando você executa git init em uma pasta, o Git cria um banco de dados de repositório local em um diretório oculto .git/. Seus arquivos existentes permanecem inalterados: eles não são preparados nem registrados em commit, e nenhum servidor remoto é contatado.

O Git compara a árvore de trabalho com o estado do repositório quando você executa comandos como git status. git init não inicia um monitor em segundo plano nem rastreia arquivos; use git add e git commit para registrar o trabalho.

O que acontece dentro de .git/ (exploração prática)

Para entender como o Git funciona, é preciso olhar dentro do diretório .git/. Vamos inicializar um repositório novo e examinar o esqueleto do banco de dados interno do Git.

Etapa 1: inicializar o diretório

Primeiro, crie um diretório novo e inicialize-o:

Os caminhos, horários, propriedade, permissões e mensagens exatas da saída do shell abaixo variam conforme o sistema operacional, a versão do Git, o usuário e a configuração; considere-os exemplos representativos.

$ mkdir git-init-deepdive && cd git-init-deepdive
$ git init
Initialized empty Git repository in /home/admin/Code/git-init-deepdive/.git/

Agora vamos listar o conteúdo da pasta .git/ recém-criada:

$ ls -al .git/
total 32
drwxr-xr-x 7 admin admin 4096 Jul  7 10:25 .
drwxr-xr-x 3 admin admin 4096 Jul  7 10:25 ..
-rw-r--r-x 1 admin admin   23 Jul  7 10:25 HEAD
-rw-r--r-x 1 admin admin   92 Jul  7 10:25 config
-rw-r--r-x 1 admin admin   73 Jul  7 10:25 description
drwxr-xr-x 2 admin admin 4096 Jul  7 10:25 hooks
drwxr-xr-x 2 admin admin 4096 Jul  7 10:25 info
drwxr-xr-x 4 admin admin 4096 Jul  7 10:25 objects
drwxr-xr-x 4 admin admin 4096 Jul  7 10:25 refs

Vamos analisar a função de cada uma dessas entradas em um repositório recém-inicializado:

1. HEAD (o ponteiro ativo)

O arquivo HEAD é um arquivo de texto simples que informa ao Git qual branch ou commit está ativo no momento. Vamos ler o conteúdo desse arquivo:

$ cat .git/HEAD
ref: refs/heads/main

Essa saída mostra que HEAD aponta para um arquivo de referência em refs/heads/main.

No entanto, se olharmos dentro do repositório, o arquivo de referência refs/heads/main ainda não existe!

$ ls -R .git/refs
.git/refs:
heads/  tags/

.git/refs/heads:
# Empty!

Esse estado é conhecido como branch não nascido. O Git aponta HEAD para o destino do branch inicial (por exemplo, main), mas não cria a referência do branch antes do primeiro commit. Neste exemplo com SHA-1 da página, a referência contém um ID de objeto de 40 caracteres hexadecimais; um repositório SHA-256 usa um comprimento de ID diferente.

2. config (configurações locais)

Esse arquivo contém configurações no nível do repositório que substituem as configurações do sistema e globais (consulte git config para obter detalhes). Vamos ver as configurações iniciais:

$ cat .git/config
[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true

Essas variáveis principais definem como o Git interage com o sistema de arquivos:

• repositoryformatversion = 0: define a versão do formato do banco de dados do repositório. Se o Git encontrar uma versão de repositório superior à que é compatível, ele se recusará a lê-la.
• filemode = true: informa ao Git que deve rastrear alterações no bit de executável dos arquivos POSIX (por exemplo, se você tornar um script executável com chmod +x).
• bare = false: declara que este é um repositório de trabalho padrão, contendo no disco arquivos com checkout. Um repositório “bare” contém apenas o diretório administrativo do Git (geralmente em servidores de hospedagem remota) e tem esse valor definido como true.
• logallrefupdates = true: instrui o Git a manter o reflog (um histórico detalhado que registra para onde as pontas dos branches e HEAD apontaram ao longo do tempo, armazenado em .git/logs/).

3. description (auxiliar legado da Web)

Este é um arquivo de texto simples que contém o marcador: Unnamed repository; edit this file 'description' to name the repository.. Ele é usado pelo GitWeb (um visualizador legado de repositórios baseado na Web). No desenvolvimento moderno, esse arquivo é ignorado e pode ser excluído com segurança ou deixado como está.

4. hooks/ (automação do ciclo de vida)

Essa pasta contém modelos de scripts shell que automatizam tarefas quando eventos do Git ocorrem (por exemplo, pre-commit, commit-msg e pre-push). Esses modelos são copiados do diretório de modelos da instalação do sistema durante a inicialização. Por padrão, todos os scripts nesse diretório terminam em .sample, o que impede sua execução. Para ativar um hook, remova a extensão .sample e torne o script executável (chmod +x).

5. info/exclude (lista de ignorados local)

Esse arquivo é usado para definir padrões de ignorados, de modo semelhante a um arquivo .gitignore. No entanto, enquanto .gitignore é registrado em commit e compartilhado com a equipe, info/exclude é apenas local. Use-o para ignorar arquivos específicos da sua máquina (como configurações do IDE local) sem afetar os ambientes de outros desenvolvedores.

6. objects/ (banco de dados de objetos)

Este é o banco de armazenamento central do repositório. Ele usa armazenamento endereçável por conteúdo para guardar objetos, que são classificados em:

• Blobs: conteúdo dos arquivos armazenados.
• Trees: hierarquias de diretórios.
• Commits: snapshots de metadados que apontam para trees e pais. Inicialmente, o banco de dados contém apenas dois subdiretórios vazios: info/ e pack/ (usados para índices de packfiles e otimização do armazenamento). O banco de dados permanece vazio até que você faça o primeiro commit.

7. refs/ (referências)

Esse diretório funciona como um índice dos ponteiros de commit do repositório. Ele contém:

• refs/heads/: abriga ponteiros de branches locais.
• refs/tags/: abriga tags (ponteiros congelados para commits históricos).
• refs/remotes/: abriga ponteiros que acompanham o estado dos branches em repositórios remotos (criados depois que um remoto é adicionado).

Opções detalhadas de comandos e uso avançado

1. Reinicializar um repositório existente

O que acontece se você executar git init em um diretório que já é um repositório Git?

$ git init
Reinitialized existing Git repository in /home/admin/Code/git-init-deepdive/.git/

Executar git init em um repositório existente é seguro. O comando não substitui seus commits, branches, índice nem arquivos de configuração. Em vez disso, verifica o diretório, repara pastas de metadados ausentes caso tenham sido excluídos acidentalmente e incorpora modelos de hooks atualizados do diretório de modelos do sistema.

2. Repositórios bare (git init --bare)

Em um repositório normal, os arquivos do projeto com checkout ficam em uma working tree ao lado do diretório .git/. Um repositório bare não tem working tree com checkout: o diretório Git do repositório é o próprio diretório de nível superior. Repositórios bare costumam ser usados como remotos compartilhados para os quais colaboradores fazem push e de onde clonam.

# Initialize a bare repository
$ git init --bare my-project.git
Initialized empty Git repository in /home/admin/Code/my-project.git/

Vamos observar a estrutura de diretórios de um repositório bare:

$ ls -F my-project.git
HEAD  config  description  hooks/  info/  objects/  refs/

Não há subdiretório .git/ nem arquivo de projeto com checkout; essas entradas são o próprio repositório. Para o trabalho do dia a dia, clone o repositório bare em um repositório de trabalho normal. O git init --bare inicia um repositório vazio — ele não copia commits de um projeto que você já tem. Para criar uma cópia bare que inclua o histórico de um repositório existente, use git clone --bare <source> <target>.git. Consulte o manual oficial do git init e o guia do Pro Git para configurar o Git em um servidor.

3. Definir o nome do branch inicial

Historicamente, o Git inicializava o branch principal padrão como master. Para adotar convenções de nomenclatura modernas, você pode especificar o nome do branch padrão durante a inicialização:

# Initialize a repository with a default branch named "main"
$ git init --initial-branch=main

Também é possível definir esse nome de branch padrão globalmente, para que todos os próximos comandos git init o apliquem automaticamente (consulte git config):

$ git config --global init.defaultBranch main

Cenário real: configurar um repositório limpo

Vamos percorrer a inicialização de um projeto novo e configurá-lo com definições padrão antes de registrar o primeiro commit.

Etapa 1: criar o diretório do projeto e inicializar o Git

$ mkdir team-portal && cd team-portal
$ git init --initial-branch=main
Initialized empty Git repository in /home/admin/Code/team-portal/.git/

Etapa 2: estabelecer as configurações do Git

Verifique as configurações do usuário local para garantir que os commits correspondam à identidade da sua equipe:

$ git config --local user.name "Alex Developer"
$ git config --local user.email "alex@portalproject.com"

Etapa 3: definir regras de ignorados

Crie um arquivo .gitignore para impedir o rastreamento de arquivos temporários ou caches do sistema:

$ echo "node_modules/" > .gitignore
$ echo ".DS_Store" >> .gitignore
$ echo "*.log" >> .gitignore

Etapa 4: escrever o código inicial e registrar o primeiro commit

Crie um arquivo, prepare-o e registre o commit:

$ echo "<h1>Team Portal</h1>" > index.html
$ git add .
$ git commit -m "chore: initial repository layout"
[main (root-commit) f23c92e] chore: initial repository layout
 2 files changed, 4 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 index.html

Vamos olhar dentro de .git/refs/heads/main agora que registramos um commit:

$ cat .git/refs/heads/main
f23c92e10db526ab1a9db3f28249a02ce5c144e1

O estado de branch não nascido foi resolvido. Neste exemplo com SHA-1 e back-end files, refs/heads/main aponta para o ID de commit ilustrativo mostrado acima; os IDs exatos variam conforme o conteúdo do repositório e os metadados do commit.

Armadilhas e erros comuns

1. Repositórios aninhados acidentais

O erro: executar git init dentro de um subdiretório de uma pasta que já é rastreada por um repositório Git.

/my-project/ (.git/ exists)
  └── /src/
        └── /components/ (runs git init here)

Por que isso é um problema: o subdiretório se torna um repositório separado. O repositório pai normalmente o vê como um diretório não rastreado (a menos que ele seja ignorado); ele não incorpora automaticamente o histórico do repositório interno. Um submódulo exige configuração explícita. A solução: verifique qual repositório contém o diretório atual antes de inicializar:

# This prints the root of the current repository, if there is one.
$ git rev-parse --show-toplevel

Se você criou o repositório aninhado por engano, remover o diretório .git/ dele transforma os arquivos em arquivos comuns na árvore de trabalho pai, mas remove permanentemente o histórico e os metadados do repositório aninhado. Confirme o caminho exato antes de excluí-lo:

$ rm -rf path/to/nested-project/.git

2. Inicializar no diretório pessoal do sistema

O erro: executar acidentalmente git init no caminho padrão do terminal (por exemplo, C:\Users\Username\ ou /home/username/). Por que isso é um problema: o Git tentará rastrear todos os arquivos do computador, incluindo arquivos da área de trabalho, downloads, aplicativos e caches do sistema. Isso deixa o terminal mais lento e provoca conflitos de commit. A solução: localize e exclua a pasta .git acidental no diretório pessoal:

# Navigate to home and delete the hidden .git directory
$ cd ~
$ rm -rf .git

(Cuidado: confirme duas vezes que você está no diretório pessoal antes de executar rm -rf .git, para não excluir o histórico de um projeto válido.)

3. Editar manualmente objetos do banco de dados

O erro: tentar modificar, renomear ou gravar manualmente arquivos dentro de .git/objects/ ou .git/refs/ para corrigir um problema do repositório. Por que isso é um problema: o banco de dados de objetos do Git depende de hashing criptográfico exato. Modificar um único caractere em um arquivo de objeto corromperá o hash e poderá tornar o repositório ilegível. A solução: use a API de linha de comando do Git para interagir com o conteúdo do repositório, em vez de editar diretamente os arquivos em .git/.

Referência rápida de comandos

Perguntas frequentes (as pessoas também perguntam)

O que git init faz?

git init transforma o diretório atual em um repositório Git ao criar um subdiretório .git/. Esse diretório contém o banco de dados de objetos, as referências de branches e a configuração local. O comando não cria um commit, ainda não rastreia nenhum arquivo e não contata nenhum servidor. Você ainda precisa executar git add e git commit antes que algo seja registrado no histórico.

git init envia meu código para o GitHub?

Não. git init é um comando local que opera inteiramente no armazenamento do seu computador. Ele inicializa um banco de dados de versões local no diretório, mas não se conecta à internet nem o vincula a hosts externos. Para enviar seu código ao GitHub, você precisa criar um repositório remoto no GitHub, vinculá-lo localmente usando git remote add e fazer push dos seus commits.

Como desfazer git init?

Para remover o rastreamento do Git de um projeto, exclua a pasta oculta .git/. Isso remove todo o histórico de commits, branches, configurações e stashes. Seus arquivos de trabalho continuarão intactos no disco, mas deixarão de ser rastreados:

$ rm -rf .git

Qual é a diferença entre um repositório Git padrão e um bare?

Um repositório Git padrão contém uma pasta .git/ ao lado de uma cópia de trabalho dos arquivos, permitindo editar e registrar alterações localmente. Um repositório bare contém apenas os arquivos do banco de dados do Git diretamente na raiz (sem pasta .git/) e não tem diretório de trabalho. Repositórios bare são usados em servidores remotos para armazenar com segurança os commits enviados.

Por que a pasta .git fica oculta por padrão?

O diretório .git/ fica oculto por padrão para evitar a modificação, movimentação ou exclusão acidental de seu conteúdo. Como todo o histórico de versões é armazenado nessa pasta, excluí-la apaga todo o histórico do repositório.

Teste seus conhecimentos