Git & GitHub
para o dev indie

Do zero ao push. Mac e Windows. Sem enrolação.

Git GitHub CLI (gh) GitHub Actions .gitignore README.md Workflows YAML

01 Instalar & logar

Mac Instalar Git + gh via Homebrew

No Mac, a forma mais fácil é pelo Homebrew. Se não tiver instalado ainda:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Depois instale o Git e o gh (CLI oficial do GitHub):

brew install git
brew install gh

Verifique que funcionou:

git --version
gh --version

Windows Instalar Git + gh

Baixe e instale o Git for Windows em git-scm.com — marque a opção "Git Bash" durante a instalação.

Depois baixe o GitHub CLI em cli.github.com (instalador .msi).

Abra o Git Bash ou o Prompt de Comando e verifique:

git --version
gh --version

Mac + Win Configurar identidade e fazer login

Configure seu nome e e-mail — isso aparece em todos os seus commits:

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

Agora faça login no GitHub via terminal com o gh:

gh auth login

Um menu interativo vai aparecer. Escolha assim:

> GitHub.com
> HTTPS
> Yes (autenticar com credencial git)
> Login with a web browser

Ele vai abrir o navegador para confirmar. Depois disso, o terminal fica logado permanentemente — não precisa repetir.

Para verificar se está logado:

gh auth status

02 Criar repositório

Situação A Criar repo novo a partir de uma pasta local

Você tem uma pasta com arquivos e quer transformá-la em repositório no GitHub:

# Entre na pasta do projeto
cd ~/meu-projeto

# Inicie o git local
git init

# Adicione os arquivos e faça o primeiro commit
git add .
git commit -m "primeiro commit"

# Crie o repo no GitHub e suba tudo de uma vez
# --public  → repositório público
# --private → repositório privado
gh repo create meu-projeto --public --source=. --remote=origin --push

O flag --push já conecta e envia tudo automaticamente. Sem ele, você precisaria fazer o push manualmente depois.

Situação B Já criei o repo no site, quero conectar à pasta local

Opção 1 — clonar (recomendado quando o repo está vazio ou só tem README):

# Baixa a pasta já conectada ao GitHub
git clone https://github.com/seu-usuario/nome-do-repo.git

# Entre na pasta
cd nome-do-repo

# Agora é só trabalhar e fazer push normalmente

Opção 2 — conectar uma pasta que já existe localmente:

# Na pasta do projeto:
git init
git remote add origin https://github.com/seu-usuario/nome-do-repo.git
git branch -M main
git add .
git commit -m "primeiro commit"
git push -u origin main

Público vs Privado via terminal

# Público (qualquer pessoa pode ver)
gh repo create meu-projeto --public --source=. --remote=origin --push

# Privado (só você e convidados)
gh repo create meu-projeto --private --source=. --remote=origin --push

# Mudar visibilidade depois
gh repo edit --visibility public
gh repo edit --visibility private

03 Arquivos importantes

.gitignore — o que é e como usar

É um arquivo de texto na raiz do projeto que diz ao Git: "ignore esses arquivos, não os mande pro GitHub". Serve para não versionar coisas desnecessárias ou perigosas — senhas, tokens de API, arquivos gerados automaticamente, pastas pesadas como node_modules.

Como criar no terminal:

# Mac
touch .gitignore

# Windows (PowerShell)
New-Item .gitignore

Exemplo de conteúdo para um projeto Node.js:

# dependências
node_modules/

# variáveis de ambiente e segredos
.env
.env.local

# gerado automaticamente pelo Mac
.DS_Store

# build
dist/
build/

# logs
*.log
.cache/

Dica: o site gitignore.io gera um .gitignore pronto para a sua linguagem. Digite "Node", "Python", "Crystal" e copie.

Atenção: arquivos que já foram commitados antes de entrar no .gitignore continuam sendo rastreados. Para parar: git rm --cached nome-do-arquivo

README.md — a vitrine do projeto

É o primeiro arquivo que as pessoas veem no GitHub. Um bom README tem: o que é, como instalar, como usar, e de que plataformas funciona. Exemplo de estrutura:

# Nome do Projeto

Descrição curta e clara do que faz.

## Instalação

```bash
brew install meu-tool
```

## Como usar

```bash
meu-tool arquivo.html --watch
```

## Plataformas suportadas

- macOS Apple Silicon (M1/M2/M3)
- macOS Intel
- Linux x64

## Licença

MIT

Peça à IA: "Me ajude a escrever um README para um projeto chamado [nome], que faz [descrição], feito em [linguagem]."

Estrutura de pasta recomendada

meu-projeto/
├── src/
│   └── main.cr          # código fonte
├── .gitignore            # o que ignorar
├── .github/
│   └── workflows/
│       └── release.yml  # GitHub Actions
└── README.md             # documentação

04 GitHub Actions

O que é GitHub Actions?

GitHub Actions é um robô automático que o GitHub executa por você. Você define: "quando acontecer X, execute Y". Por exemplo: toda vez que você criar uma nova versão (tag), ele compila o projeto para Mac ARM, Mac Intel e Linux, e já cria um release com os binários automaticamente.

Os arquivos ficam em .github/workflows/nome.yml e são escritos em YAML — um formato de texto com indentação que representa listas e valores.

Para dev indie, o uso mais comum é: build automático + release. Você faz push com uma tag e o GitHub compila e distribui por você, sem precisar de servidor próprio.

Workflow completo de Release — Mac ARM, Mac Intel, Linux

name: Release
on:
  push:
    tags:
      - 'v*'  # dispara quando você faz push de uma tag tipo v1.0.0
jobs:
  build-macos-arm64:
    runs-on: macos-26  # Mac Apple Silicon (M1/M2/M3)
    steps:
      - uses: actions/checkout@v4
      - uses: crystal-lang/install-crystal@v1
      - run: crystal build src/main.cr -o easybrawto-macos-arm64 --release
      - uses: actions/upload-artifact@v4
        with:
          name: easybrawto-macos-arm64
          path: easybrawto-macos-arm64

  build-macos-x64:
    runs-on: macos-26-intel  # Mac Intel (macOS 26 Tahoe)
    steps:
      - uses: actions/checkout@v4
      - uses: crystal-lang/install-crystal@v1
      - run: crystal build src/main.cr -o easybrawto-macos-x64 --release
      - uses: actions/upload-artifact@v4
        with:
          name: easybrawto-macos-x64
          path: easybrawto-macos-x64

  build-linux-x64:
    runs-on: ubuntu-latest  # Linux x64
    steps:
      - uses: actions/checkout@v4
      - uses: crystal-lang/install-crystal@v1
      - run: crystal build src/main.cr -o easybrawto-linux-x64 --release
      - uses: actions/upload-artifact@v4
        with:
          name: easybrawto-linux-x64
          path: easybrawto-linux-x64

  release:
    needs: [build-macos-arm64, build-macos-x64, build-linux-x64]
    runs-on: ubuntu-latest
    permissions:
      contents: write  # permissão para criar o release
    steps:
      - uses: actions/download-artifact@v4
      - uses: softprops/action-gh-release@v1
        with:
          files: |
            easybrawto-macos-arm64/easybrawto-macos-arm64
            easybrawto-macos-x64/easybrawto-macos-x64
            easybrawto-linux-x64/easybrawto-linux-x64

Como entender o YAML — linha a linha

Gatilho

on: push: tags: - 'v*' — o workflow roda quando você faz push de qualquer tag que começa com v, como v1.0.0 ou v2.3.1.

Jobs paralelos

Cada build-* roda em paralelo em máquinas diferentes do GitHub. O job release usa needs: para esperar todos terminarem.

runs-on

macos-26 = Apple Silicon · macos-26-intel = Intel · ubuntu-latest = Linux x64. São VMs gratuitas do GitHub.

upload / download artifact

Os binários compilados são salvos como "artifacts" entre jobs. O job release baixa todos e anexa ao release do GitHub.

Como criar o arquivo e acionar o release

# Crie as pastas necessárias
mkdir -p .github/workflows

# Crie o arquivo (Mac)
touch .github/workflows/release.yml

# Cole o conteúdo YAML, depois:
git add .github/workflows/release.yml
git commit -m "add: workflow de release automático"
git push

Para disparar o release, crie uma tag e faça push:

# Crie a tag (ex: v1.0.0)
git tag v1.0.0

# Envie a tag para o GitHub — isso aciona o Actions
git push origin v1.0.0

Acompanhe o progresso em: github.com → seu repo → aba Actions. Cada job aparece em tempo real.

05 Dia a dia

O ciclo básico — 3 comandos que você usa sempre

# 1. Adicionar mudanças ao próximo commit
git add .

# 2. Salvar um ponto no histórico com descrição
git commit -m "descreva o que mudou aqui"

# 3. Enviar para o GitHub
git push

Pense assim: add = selecionar o que vai · commit = salvar localmente com uma descrição · push = enviar para o GitHub.

git add . vs git add arquivo — quando usar cada um

git add . — tudo de uma vez

git add .

Use quando suas mudanças são relacionadas e você quer commitar tudo junto. É o mais comum no dia a dia.

git add arquivo — só um arquivo

git add src/main.cr
git add README.md

Use quando você mexeu em vários arquivos mas quer commits separados e organizados — um commit por funcionalidade.

Antes de adicionar, rode git status para ver o que mudou. Para ver o que mudou linha a linha: git diff

Quando fazer git push?

Não tem regra rígida — mas boas práticas para dev indie:

✓

Ao final de cada sessão de trabalho — funciona como um "salvar na nuvem"

✓

Quando terminar uma funcionalidade ou correção, mesmo que pequena

✓

Antes de fazer mudanças grandes — garante um ponto de retorno seguro

✓

Antes de criar uma release (tag de versão)

Evite commits com mensagens tipo "fix", "wip", "asdf". Isso polui o histórico e dificulta entender o que mudou — ou voltar para um ponto específico depois.

Comandos úteis do dia a dia

# Ver o status da pasta (o mais usado de todos)
git status

# Ver histórico de commits resumido
git log --oneline

# Ver o que mudou linha a linha
git diff

# Criar uma branch nova (para features experimentais)
git checkout -b nome-da-feature

# Voltar para a branch principal
git checkout main

# Criar tag de versão e enviar (aciona o Actions)
git tag v1.0.0
git push origin v1.0.0

# Ver repositórios remotos conectados
git remote -v

# Ver seus repos no GitHub via terminal
gh repo list

# Abrir o repositório no navegador direto do terminal
gh repo view --web

06 Cenários comuns

Erro: "failed to push — Updates were rejected"

O GitHub tem commits que você não tem localmente. Acontece quando você (ou outra pessoa) fez push de outro lugar.

git pull --rebase origin main
git push

Erro: "src refspec main does not match any"

Você tentou dar push mas ainda não fez nenhum commit. O Git não tem nada para enviar.

git add .
git commit -m "primeiro commit"
git push -u origin main

Erro: "Permission denied" ou "Authentication failed"

Token expirou ou você não está logado. Refaça o login:

gh auth login

Esqueci de adicionar um arquivo ao último commit

git add arquivo-esquecido
git commit --amend --no-edit

Só faça --amend se ainda não tiver dado push. Depois do push, o amend causa problemas de histórico divergente.

Quero desfazer o último commit (mas manter os arquivos)

# Os arquivos voltam para "staged" — só o commit é desfeito
git reset --soft HEAD~1

Arquivo grande bloqueou o push (acima de 100MB)

# Adicione ao .gitignore e remova do rastreamento
echo "arquivo-grande.zip" >> .gitignore
git rm --cached arquivo-grande.zip
git commit -m "remove arquivo grande do rastreamento"
git push

Quero ver os commits de outro jeito (com gráfico de branches)

git log --oneline --graph --all

Quero clonar só uma branch específica

git clone --branch nome-da-branch https://github.com/usuario/repo.git

07 Pedindo ajuda à IA

Regra de ouro

Cole sempre a mensagem de erro completa. A IA não consegue adivinhar o que deu errado sem ver o erro exato. Quanto mais contexto você der, mais precisa será a resposta.

Sistema operacional + linguagem + versão + o que você estava tentando fazer + o erro completo = resposta certeira na primeira tentativa.

Templates prontos para cada situação

Para erros no terminal

Estou usando Mac com Apple Silicon, Git 2.x Rodei esse comando: [cole o comando] Recebi esse erro: [cole o erro completo] O que isso significa e como resolver?

Para criar .gitignore

Me ajude a criar um .gitignore para um projeto Crystal que compila para binários e usa shards como dependências. A pasta de build se chama "bin/".

Para escrever o README

Me ajude a escrever um README.md para um projeto chamado [nome], que é uma [descrição], feito em [linguagem], com instalação via brew e binários para Mac e Linux. O tom deve ser simples e direto.

Para erros no GitHub Actions

Tenho esse workflow do GitHub Actions que não está funcionando. Ele deveria [descrever o objetivo]. O erro que aparece na aba Actions do GitHub é: [cole o log de erro completo] Aqui está o YAML completo: [cole o arquivo]

Para entender um comando

Explica o que esse comando git faz, passo a passo, como se eu fosse iniciante: [cole o comando]

Como encontrar os logs de erro do GitHub Actions

Vá no seu repositório no GitHub → clique na aba Actions

Clique no run que falhou (ícone vermelho)

Clique no job com erro → expanda o step que falhou

Copie esse log inteiro e cole na IA

Você também pode abrir o Actions direto do terminal: gh run list para ver os runs e gh run view --log para ver o log do último run.

# Ver runs do Actions no terminal
gh run list

# Ver log do último run com falha
gh run view --log-failed

Git & GitHubpara o dev indie

Gatilho

Jobs paralelos

runs-on

upload / download artifact

git add . — tudo de uma vez

git add arquivo — só um arquivo

Para erros no terminal

Para criar .gitignore

Para escrever o README

Para erros no GitHub Actions

Para entender um comando

Git & GitHub
para o dev indie