GitHub do iniciante ao mestre: um guia completo

Se você quer ganhar dinheiro com GitHub, o caminho mais direto não é complicado: sob a premissa de permissão de licença, encontre projetos open-source valiosos, transforme implantação, documentação em chinês e suporte pós-venda em um serviço, e venda a entrega em plataformas como Xianyu.

No entanto, o que realmente gera dinheiro é a capacidade de filtrar informações e implementar. Se você quer trabalhar com IA, migrar para FDE (Engenheiro de Desenvolvimento Full-stack) ou se transformar em uma OPC (Empresa de Uma Pessoa), código, documentação, versões e colaboração acabarão no GitHub.

Mesmo que você esteja criando conteúdo ou trabalhando com mídia própria, há uma grande quantidade de ferramentas de seleção de tópicos, projetos de automação e processos de produção de conteúdo no GitHub. Quando os arquivos aumentam e a IA faz alterações, sem o Git para gerenciar versões, as coisas rapidamente saem do controle. Portanto, programadores precisam aprender, assim como gerentes de projeto e criadores de conteúdo; isso determina se você consegue transformar uma ideia em um projeto gerenciável, reutilizável e entregável.

Passei mais de meio mês refinando este artigo, praticando Git, GitHub, Commits, branches, PRs e erros comuns do zero. As transmissões ao vivo futuras também seguirão este mesmo processo. Antes da transmissão oficial, estou abrindo este tutorial primeiro. Você pode salvá-lo ou segui-lo completamente.

1. Git e GitHub: Quem Gerencia o Quê?

Git é uma ferramenta de gerenciamento de versão instalada no seu computador. Quando offline, você ainda pode fazer commit, ver histórico, criar branches e fazer merge. GitHub é uma plataforma de repositório remoto e colaboração; ele recebe os commits enviados pelo Git e fornece Issues, Pull Requests, Actions, revisões de código e gerenciamento de permissões.

A coisa mais fácil de confundir no Git é que a mesma modificação pode existir em quatro locais diferentes. O infográfico abaixo divide o workspace, staging area, repositório local e repositório remoto em quatro camadas.

Pressionar salvar apenas escreve o conteúdo no disco rígido. git add é responsável por selecionar, git commit deixa uma versão localmente, e git push envia esses commits para o GitHub.

Então, antes de commitar, verifique o diff, execute ou teste; após enviar com sucesso, volte à página web para verificar novamente. Dessa forma, se um problema ocorrer, você saberá imediatamente em qual camada ele parou.

2. Antes de Começar: Prepare Apenas Quatro Coisas

Você precisa do Git, uma conta no GitHub, um editor e um projeto para praticar. VS Code é suficiente para o editor, e o projeto pode ser uma página web ou um documento Markdown.

Primeiro, confirme o Git no terminal:

1git --version

Este exercício usa macOS e Git 2.49.0. Usuários do Windows podem usar Git Bash ou o terminal integrado do VS Code; os comandos Git abaixo são os mesmos.

Em seguida, configure o autor do commit:

1git config --global user.name "Seu Nome"
2git config --global user.email "Seu Email"

Esta é a informação do autor escrita no registro do commit; não é responsável por fazer login no GitHub. Se você quiser configurar apenas para o projeto de prática atual, substitua --global por --local.

O login no GitHub é uma questão separada. A linha de comando comumente usa três métodos:

• GitHub CLI, autorizando via navegador com gh auth login;
• HTTPS, usando um Personal Access Token ou gerenciador de credenciais;
• SSH, adicionando uma chave pública ao GitHub e autenticando via chave posteriormente.

Iniciantes podem escolher GitHub CLI ou HTTPS. Ao usar HTTPS, se o terminal pedir uma Senha, preencha o Token; senhas de conta comuns não são mais aplicáveis. Não escreva o Token em comandos, URLs remotas, READMEs, chats ou capturas de tela.

3. Não se Apresse para o init: Confirme Onde o Terminal Realmente Está

Este exercício começa com uma página web simples. Ela pode ser aberta em um navegador, mas ainda não tem histórico Git.

Há três arquivos no projeto:

1index.html
2style.css
3.gitignore

No VS Code, selecione "Abrir Pasta", não clique apenas em um arquivo HTML. Em seguida, execute no terminal integrado:

1pwd
2ls

pwd mostra o diretório atual, e ls lista os arquivos. Continue apenas depois de ver index.html e style.css.

Esta verificação parece boba, mas previne o tipo mais problemático de acidente: alguém executando git init na Área de Trabalho, Documentos ou até mesmo no diretório home do usuário, e então git add . colocando milhares de arquivos irrelevantes na staging area. Git não está quebrado; o diretório estava errado.

4. O Que o git init Faz?

Agora inicialize o repositório:

1git init -b main
2git status --short

git init -b main cria um diretório .git na pasta atual e nomeia a branch inicial como main. .git é um diretório oculto onde informações como commits, branches, staging area e endereços remotos são armazenadas. Os arquivos do projeto permanecem no lugar; Git começa a observá-los a partir deste momento.

O ?? na captura de tela indica arquivos não rastreados. Os arquivos existem, mas Git ainda não decidiu se deve registrá-los.

Para confirmar o diretório raiz do repositório, você pode executar:

1git rev-parse --show-toplevel

A saída deve ser a pasta do projeto atual. Se disser fatal: not a git repository, verifique o diretório primeiro, depois veja se git init foi executado.

5. O Primeiro Commit: Mantenha um Ponto de Partida Confiável

O projeto ainda não foi modificado, então por que commitar primeiro? Porque todas as alterações subsequentes precisam de um ponto de partida comparável. Primeiro, abra a página web em um navegador para confirmar se o título, cards e área de registro são exibidos; estreite a janela para ver se há rolagem horizontal na largura do celular.

Em seguida, veja o .gitignore. O conteúdo usado desta vez é:

1.env
2.env.*
3*.log
4node_modules/
5dist/
6build/

.gitignore é usado para bloquear chaves, logs, dependências e artefatos de build. Ele funciona principalmente em arquivos que ainda não estão sendo rastreados. Se uma chave já foi commitada e você a adiciona ao .gitignore depois, esse histórico ainda existe; o tratamento real também inclui revogar ou rotacionar a chave.

Comece selecionando arquivos para o primeiro commit:

1git add index.html style.css .gitignore
2git status --short
3git diff --cached --stat

O A no status significa Adicionado (Added), indicando que o arquivo entrou na staging area. git diff --cached --stat informará quantos arquivos você está se preparando para commitar e aproximadamente quantas linhas foram alteradas. Para ver o conteúdo específico, execute:

1git diff --cached

Commite após a confirmação:

1git commit -m "chore: Inicializar página de recrutamento de IA no campus"
2git log --oneline
3git status

Um Commit pode ser entendido como um instantâneo do projeto com autor, hora, descrição e commit pai. ffdf4ff é a versão curta deste hash de commit; usá-lo no repositório atual pode localizar a versão com precisão.

feat, fix, docs, style, chore são tipos de commit comuns, não uma sintaxe obrigatória do Git. Mais importante que o prefixo é a descrição em português (ou inglês) que o segue: o que foi feito, qual objeto foi modificado e por quê.

6. O Segundo Commit: Trate as Modificações da IA como Rascunhos para Revisão

Em seguida, adicione um botão "Ver Método de Inscrição" à página. Ao usar ferramentas de programação de IA, escrevo limites no prompt:

1Modifique apenas index.html, adicione um link "Ver Método de Inscrição" abaixo do texto de introdução,
2linkando para #apply dentro da página. Não modifique style.css, não execute commits Git.
3Diga-me qual arquivo foi modificado quando terminar.

A modificação manual também é simples:

1<a class="cta" href="#apply">Ver Método de Inscrição</a>

A IA diz que está pronto, mas não commite ainda. Execute:

1git status --short
2git diff -- index.html
3git diff --check

git diff mostra as alterações no workspace que ainda não foram preparadas (staged). + verde é uma linha adicionada, - vermelho é uma linha deletada. git diff --check não tem saída, indicando que nenhum problema óbvio de formatação, como espaços à direita, foi encontrado; ele não verifica se o botão é clicável para você.

Volte ao navegador e atualize, clique no botão, depois estreite a janela. A página deve rolar para a área de registro, e o botão e os cards ainda devem estar normais em telas estreitas.

Commite apenas depois que o teste passar:

1git add index.html
2git diff --cached
3git commit -m "feat: Adicionar entrada de registro para visualização rápida dos métodos de inscrição"
4git log --oneline -2

Neste ponto, há duas versões claras no repositório: a página inicial e o botão de registro. Se o botão tiver problemas mais tarde, você pode encontrar diretamente qual commit o adicionou.

A propósito, distinga os dois diffs:

1git diff             # Diferença entre workspace e staging area
2git diff --cached    # Diferença entre staging area e o commit mais recente

Se git diff não tiver saída, o arquivo pode não ter sido salvo, ou pode já ter sido preparado (staged) ou commitado. Verificar git status, git diff --cached e git log em sequência é mais confiável do que digitar git add . repetidamente.

7. Branches: Deixe um Ponto de Teste para Mudanças Incertas

O botão adiciona apenas uma linha, então o risco é pequeno. Mudar todo o tema de roxo para laranja pode ficar bom ou pode ficar brega; esse tipo de modificação é adequado para uma branch.

1git switch -c experiment/warm-theme
2git branch --show-current

Uma branch é conceitualmente um nome que aponta para um determinado commit. Quando uma nova branch é criada pela primeira vez, ela aponta para o mesmo commit que main, então os arquivos são exatamente os mesmos. Apenas quando a branch experimental gera novos commits é que as duas linhas divergem.

No diagrama, o main azul ainda aponta para o segundo commit, enquanto o experiment laranja já aponta para o terceiro commit. O projeto não duplicou dois conjuntos de arquivos; apenas os ponteiros para os dois nomes de branch mudaram.

Modifique as variáveis de cor em style.css, atualize a página para confirmar e então commite:

1git diff -- style.css
2git diff --check
3git add style.css
4git commit -m "style: Experimentar tema quente na branch experimental"
5git log --oneline --graph --decorate --all

HEAD indica onde você está atualmente. Na captura de tela, HEAD aponta para experiment/warm-theme, enquanto main permanece no commit do botão.

Decida manter o tema quente, volte para main e faça o merge:

1git switch main
2git merge experiment/warm-theme

Um Fast-forward ocorre aqui porque main não teve novos commits durante o experimento. Git move diretamente o ponteiro main para frente até o commit do tema quente; as alterações foram mescladas com sucesso.

Branches mescladas podem ser deletadas com segurança:

1git branch -d experiment/warm-theme

-d minúsculo verifica se a branch foi mesclada. -D maiúsculo forçará a exclusão, e commits na branch que não foram mesclados podem perder suas referências; não use como comando de limpeza diária.

8. Conflitos Não São Misteriosos; Git Apenas Não Ousa Escolher por Você

Para verificar conflitos, dupliquei o repositório. main mudou o título principal para "Deixe a criatividade do campus ser vista por mais pessoas", e a branch feature mudou a mesma linha para "Transforme uma ideia em um trabalho verdadeiramente utilizável". Git parou durante o merge:

Os marcadores de conflito são divididos em três partes:

1<<<<<<< HEAD
2Conteúdo da branch atual
3=======
4Conteúdo da branch a ser mesclada
5>>>>>>> feature/rewrite-heading

O método de tratamento é editar o arquivo, deixar o texto final desejado, deletar os três conjuntos de marcadores, testar e então executar:

1git add index.html
2git commit

Se você não quiser lidar com isso naquele momento, pode abortar o merge:

1git merge --abort

Um conflito significa que duas pessoas ou dois Agentes deram respostas diferentes para o mesmo local, e Git não pode escolher por conta própria.

9. Enviando o Repositório Local para o GitHub

O projeto já tem um histórico local; agora vá ao GitHub para criar um repositório. Clique no + no canto superior direito, selecione "New repository" e preencha o nome do repositório, por exemplo:

1campus-ai-demo

Para a primeira prática, é recomendado configurá-lo como Privado (Private). Como o local já tem um README, .gitignore e histórico de commits, mantenha o novo repositório GitHub em branco; não inicialize README, licença ou .gitignore no lado web. Caso contrário, o local e o remoto terão cada um um pedaço de histórico inicial, e o primeiro push exigirá lidar com a relação entre os dois lados primeiro. O guia oficial do GitHub "Adding locally hosted code" também lembra explicitamente disso.

Copie o endereço HTTPS:

1https://github.com/SeuNomeDeUsuario/campus-ai-demo.git

Volte ao terminal do projeto:

1git remote add origin https://github.com/SeuNomeDeUsuario/campus-ai-demo.git
2git remote -v
3git push -u origin main

origin é um alias para o endereço remoto; pode funcionar com outros nomes, mas a comunidade costuma chamar o repositório remoto principal de origin. -u estabelecerá uma relação de rastreamento entre o main local e origin/main; operações subsequentes geralmente executam apenas git push.

O diagrama do terminal abaixo usou um repositório bare local para executar push e clone, então não alterou a conta GitHub existente. Ao mudar para o GitHub, basta substituir a URL do origin; a lógica para Git passar commits e estabelecer relações de rastreamento é a mesma.

Após o push real ser concluído, volte à página web do GitHub e atualize para confirmar que arquivos, README, branch padrão e histórico de commits estão todos visíveis. A mensagem de sucesso no terminal é uma camada de evidência, e a verificação web é outra.

10. Lendo um Repositório GitHub pela Primeira Vez: Como Ler Essas Coisas na Página

Abaixo está a página real do repositório de documentação oficial do GitHub, capturada em 15 de agosto de 2026.

Ao abrir um repositório, veja estes locais primeiro:

• Code: Arquivos, diretórios, branches e commits;
• Issues: Bugs, requisitos, tarefas e discussões;
• Pull requests: Alterações aguardando revisão ou merge;
• Actions: Testes automatizados, build e implantação;
• Security: Políticas de segurança e funções relacionadas a vulnerabilidades;
• Insights: Contribuições, tráfego e atividade do repositório;
• README: Introdução do projeto e entrada de uso;
• LICENSE: Como é permitido usar, modificar e distribuir.

Ao ler um projeto desconhecido, não olhe primeiro para as Estrelas (Stars). Responda a cinco perguntas primeiro: Que problema ele resolve, como ele funciona, do que depende, é mantido recentemente e o que a licença me permite fazer. Estrelas refletem atenção; elas não verificam segurança, compatibilidade ou autorização para você.

11. clone, fetch, pull, push: Não Confunda as Quatro Direções

Pegar um repositório remoto para o seu computador pela primeira vez:

1git clone https://github.com/PROPRIETARIO/REPO.git

Clone traz de volta arquivos, histórico de commits e configurações remotas, geralmente nomeando o remoto como origin automaticamente. Baixar um ZIP dá apenas um instantâneo dos arquivos naquele momento, sem histórico completo, e não estabelecerá uma relação remota.

As três ações comumente usadas depois são:

1git fetch origin   # Baixa informações remotas, não altera os arquivos de trabalho atuais
2git pull           # fetch e depois integra na branch atual
3git push           # Envia commits locais para o remoto

Para ver o que aconteceu remotamente primeiro, você pode:

1git fetch origin
2git status -sb
3git log --oneline HEAD..origin/main

Ao confirmar que não há divergência local e você deseja aceitar apenas atualizações fast-forward:

1git pull --ff-only

pull fará fetch primeiro e, em seguida, executará merge ou rebase com base na configuração. As equipes devem concordar com o método de integração antes da primeira colaboração e não confiar em force push para resolver problemas quando ocorrer divergência.

12. Do Repositório Pessoal à Colaboração no GitHub

Um Pull Request é uma proposta de merge e onde a colaboração acontece. Discussões, revisões de código e verificações automatizadas giram em torno do mesmo conjunto de alterações, e ele é mesclado em main somente após a confirmação.

Supondo que a Issue seja "Adicionar descrição do horário do evento", as operações locais podem ser feitas assim:

1git switch -c feat/event-time
2# Modificar e testar a página
3git add index.html
4git commit -m "feat: Adicionar descrição do horário do evento"
5git push -u origin feat/event-time

Após o push, o GitHub geralmente solicita a criação de um Pull Request. Um PR é uma proposta de merge que exibe descrições, commits, diferenças de arquivos, comentários, revisões e verificações automatizadas. Ele não entrará automaticamente em main apenas por ter sido criado.

Um PR que as pessoas estão dispostas a revisar deve explicar pelo menos três coisas: o que foi alterado, por que foi alterado e como verificar. Quanto mais focadas as alterações, mais fácil para os revisores identificarem problemas.

Na mesma equipe, se você tiver acesso de escrita ao repositório, pode enviar um PR diretamente de uma branch. Ao contribuir para um projeto open-source desconhecido, a prática comum é fazer um Fork para sua própria conta primeiro e depois clonar seu próprio Fork:

1git clone https://github.com/SeuNomeDeUsuario/NomeDoProjeto.git
2cd NomeDoProjeto
3git remote add upstream https://github.com/AutorOriginal/NomeDoProjeto.git
4git remote -v

Geralmente há dois remotos aqui:

1origin    Seu próprio Fork
2upstream  Repositório do autor original

Sincronize o projeto original:

1git fetch upstream
2git switch main
3git merge --ff-only upstream/main
4git push origin main

Em seguida, complete as modificações em uma nova branch, faça push para seu próprio Fork e então envie um PR para upstream. Fork, clone e branch resolvem três coisas diferentes: Fork é um conjunto de espaço de repositório no GitHub, clone traz o repositório para o local, e branch é uma linha de desenvolvimento dentro de um repositório.

13. README e LICENSE Determinam se os Outros Ousam Usá-lo

Um README deve responder pelo menos a estas perguntas:

1. O que é o projeto;
2. Que problema ele resolve;
3. Como instalar ou executá-lo;
4. Até que ponto está atualmente concluído;
5. Onde estão os principais arquivos;
6. Quem são os autores, materiais e fontes de citação.

Se o código pode ser executado, mas o README é vago, você pode não conseguir retomá-lo três meses depois. Um README mínimo não precisa ser bonito; apenas escreva o projeto, o método de execução e o status claramente.

Repositórios públicos também não significam automaticamente a obtenção de uma licença open-source. A explicação oficial da licença do GitHub afirma claramente: quando não há licença, as regras de direitos autorais padrão ainda se aplicam, e o autor retém os direitos de copiar, distribuir e criar trabalhos derivados. Público significa que outros podem vê-lo e fazer Fork de acordo com os termos de serviço do GitHub; para pegar o código para seu próprio projeto público ou comercial, você também precisa olhar a LICENÇA no repositório.

MIT, Apache-2.0, GPL, etc., têm diferentes obrigações. Ao encontrar uso comercial, redistribuição ou licenças mistas, leia o arquivo completo e consulte um profissional, se necessário; não pergunte apenas a uma IA "Posso usar para fins comerciais?"

14. Depois de Cometer um Erro: Determine em Qual Camada a Mudança Está

O remédio para arrependimento deve ser escolhido por estado.

Preparou (staged) o arquivo errado, mas quer manter o conteúdo do arquivo:

1git restore --staged nome_do_arquivo

A mensagem do commit mais recente foi escrita incorretamente e ainda não foi enviada (pushed):

1git commit --amend -m "Nova mensagem do commit"

Um commit em uma branch compartilhada precisa ser revertido:

1git revert hash_do_commit

revert produzirá um novo commit reverso, e o histórico antigo permanece visível, o que é adequado para branches que já foram enviadas e são usadas por várias pessoas.

git restore nome_do_arquivo descartará modificações que não foram commitadas; git reset --hard fará com que os commits, staging area e workspace retornem a uma posição especificada; git push --force pode sobrescrever commits remotos. Esses três tipos de operações exigem confirmação do alvo e backup antes da execução; não os trate como botões gerais de reparo na fase de zero-base.

15. Oito Erros Mais Comuns: Verifique Nesta Ordem

1. fatal: not a git repository

1pwd
2ls
3git status

Geralmente, o diretório está errado, ou o projeto atual ainda não foi inicializado com git init.

2. Author identity unknown

1git config --local user.name "Seu Nome"
2git config --local user.email "Seu Email"

3. nothing to commit

Verifique se o arquivo foi salvo, se você modificou outra cópia e se as alterações já foram commitadas:

1git status
2git log --oneline -3

4. remote origin already exists

1git remote -v
2git remote set-url origin EnderecoGitHubCorreto

5. src refspec main does not match any

O repositório pode não ter um commit ainda, ou a branch atual não se chama main:

1git log --oneline
2git branch --show-current

6. Authentication failed or 403

Verifique a URL remota, a propriedade do repositório, as permissões da conta e o método de autenticação. Não envie o Token para outros para solução de problemas.

7. rejected non-fast-forward

Há commits remotamente que não estão localmente. Faça fetch e veja as diferenças primeiro; não faça force push diretamente:

1git fetch origin
2git status -sb
3git log --oneline --graph --decorate --all -10

8. Merge Conflict

Execute git status para encontrar arquivos UU, determine manualmente o conteúdo final, teste, depois add e commit; se não for lidar com isso por enquanto, git merge --abort.

Quando um aluno ou colega simplesmente diz "O Git está quebrado", peça a eles que forneçam estas cinco saídas:

1pwd
2git status
3git branch --show-current
4git log --oneline -5
5git remote -v

Em seguida, adicione o sistema operacional, o comando completo que acabou de ser executado e a mensagem de erro completa. A maioria dos problemas rapidamente se encaixará em uma das camadas: diretório, status, identidade, endereço remoto ou permissão.

16. Na Era da IA, o Git é Mais Como um Sistema de Aceitação

A IA pode digitar comandos para você, mas não pode saber automaticamente quais modificações atendem às intenções de negócio. Se um prompt altera 20 arquivos e você não olha o diff, não executa o projeto e não verifica as chaves, o Git apenas registrará fielmente essa bagunça.

Uma maneira mais estável é restringir a tarefa e colocar o humano na posição de aceitação. Depois que o escopo, as diferenças, os testes e as verificações de chave passarem, o humano decide se essas modificações podem se tornar um commit.

Ao deixar a IA operar o Git, também dê limites:

1Por favor, verifique o git status e o git diff primeiro, e apenas resuma as alterações atuais.
2Não descarte nenhum conteúdo não commitado, não execute reset --hard, clean ou force push.
3Forneça os resultados da verificação após concluir as modificações, não faça commit ou push automaticamente.

Se você consegue memorizar comandos não é mais tão importante. Você precisa ser capaz de ler o status, saber o que a IA moveu, julgar se a verificação é suficiente e interromper quando operações perigosas aparecerem.

17. Execute Todo o Processo Novamente

1# 1. Confirmar localização
2pwd
3ls
4
5# 2. Inicializar
6git init -b main
7git status
8
9# 3. Primeiro commit
10git add index.html style.css .gitignore
11git diff --cached
12git commit -m "chore: Inicializar projeto"
13
14# 4. Modificar, verificar, testar, commitar novamente
15git status --short
16git diff
17git diff --check
18git add index.html
19git commit -m "feat: Adicionar entrada de registro"
20
21# 5. Experimento de branch
22git switch -c experiment/warm-theme
23git add style.css
24git commit -m "style: Experimentar tema quente"
25git switch main
26git merge experiment/warm-theme
27
28# 6. Conectar ao GitHub
29git remote add origin https://github.com/YourUsername/RepoName.git
30git remote -v
31git push -u origin main
32
33# 7. Verificação final
34git status
35git log --oneline --graph --decorate --all
36git remote -v
37git diff --check
38git ls-files

Quando você consegue explicar qual camada cada comando alterou, e consegue lidar de forma independente com um diretório errado, um erro de staging e um conflito de merge, o GitHub deixa de ser apenas um site para armazenar código. Você já é capaz de transformar projetos pessoais em repositórios que podem ser revisados, auditados e colaborados.

O próximo passo não requer continuar colecionando comandos. Encontre um pequeno projeto real e faça-o por 7 dias consecutivos: complete apenas uma pequena modificação a cada dia, olhe o diff, teste, faça commit e então faça push para o GitHub. O histórico de commits lentamente transformará esse conjunto de coisas em seu hábito de trabalho.

Eu sou Miles, um especialista em algoritmos de IA que migrou de uma grande empresa para FDE. Já trabalhei com pesquisa e desenvolvimento de algoritmos, implantação de otimização e treinamento corporativo. Siga-me @miles_mazy Cresçamos juntos, ganhemos dinheiro juntos.