18 KiB

Raw Permalink Blame History

Introdução ao GitHub

Esta lição aborda os conceitos básicos do GitHub, uma plataforma para hospedar e gerir alterações no seu código.

Sketchnote por Tomomi Imura

Questionário Pré-Aula

Questionário pré-aula

Introdução

Nesta lição, vamos abordar:

como rastrear o trabalho que faz no seu computador
como trabalhar em projetos com outras pessoas
como contribuir para software de código aberto

Pré-requisitos

Antes de começar, verifique se o Git está instalado. No terminal, digite:
git --version

Se o Git não estiver instalado, faça o download do Git. Depois, configure o seu perfil local do Git no terminal:

git config --global user.name "seu-nome"
git config --global user.email "seu-email"

Para verificar se o Git já está configurado, pode digitar:
git config --list

Também precisará de uma conta no GitHub, um editor de código (como o Visual Studio Code) e de abrir o seu terminal (ou prompt de comando).

Acesse github.com e crie uma conta, caso ainda não tenha, ou faça login e preencha o seu perfil.

✅ O GitHub não é o único repositório de código no mundo; existem outros, mas o GitHub é o mais conhecido.

Preparação

Vai precisar de uma pasta com um projeto de código no seu computador (portátil ou PC) e de um repositório público no GitHub, que servirá como exemplo de como contribuir para os projetos de outras pessoas.

Gestão de Código

Vamos supor que tem uma pasta localmente com um projeto de código e quer começar a rastrear o seu progresso usando o Git - o sistema de controlo de versões. Algumas pessoas comparam o uso do Git a escrever uma carta de amor para o seu "eu" do futuro. Ao ler as mensagens de commit dias, semanas ou meses depois, será capaz de recordar por que tomou uma decisão ou "reverter" uma alteração - isto, claro, se escrever boas mensagens de commit.

Tarefa: Criar um repositório e fazer commit do código

Veja o vídeo

Criar um repositório no GitHub. No GitHub.com, na aba de repositórios ou na barra de navegação no canto superior direito, encontre o botão novo repositório.
1. Dê um nome ao seu repositório (pasta).
2. Selecione criar repositório.
Navegar até à sua pasta de trabalho. No terminal, mude para a pasta (também conhecida como diretório) que deseja começar a rastrear. Digite:
```
cd [name of your folder]
```
Inicializar um repositório Git. No seu projeto, digite:
```
git init
```
Verificar o estado. Para verificar o estado do seu repositório, digite:
```
git status
```
A saída pode ser algo como isto:
```
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

     modified:   file.txt
     modified:   file2.txt
```
Normalmente, o comando git status informa coisas como quais ficheiros estão prontos para serem salvos no repositório ou têm alterações que talvez queira persistir.
Adicionar todos os ficheiros para rastreamento
Isto também é chamado de "staging" de ficheiros/adicionar ficheiros à área de staging.
```
git add .
```
O comando git add com o argumento . indica que todos os seus ficheiros e alterações serão rastreados.
Adicionar ficheiros selecionados para rastreamento
```
git add [file or folder name]
```
Isto permite adicionar apenas ficheiros selecionados à área de staging quando não deseja fazer commit de todos os ficheiros de uma vez.
Remover todos os ficheiros da área de staging
```
git reset
```
Este comando permite remover todos os ficheiros da área de staging de uma vez.
Remover um ficheiro específico da área de staging
```
git reset [file or folder name]
```
Este comando permite remover apenas um ficheiro específico da área de staging que não deseja incluir no próximo commit.
Persistir o seu trabalho. Neste ponto, adicionou os ficheiros a uma chamada área de staging. Um local onde o Git está a rastrear os seus ficheiros. Para tornar a alteração permanente, precisa de fazer um commit dos ficheiros. Para isso, crie um commit com o comando git commit. Um commit representa um ponto de salvamento na história do seu repositório. Digite o seguinte para criar um commit:
```
git commit -m "first commit"
```
Isto faz o commit de todos os seus ficheiros, adicionando a mensagem "primeiro commit". Para mensagens de commit futuras, será mais útil ser descritivo na sua descrição para transmitir o tipo de alteração que fez.
Conectar o seu repositório Git local ao GitHub. Um repositório Git é útil no seu computador, mas, em algum momento, vai querer ter um backup dos seus ficheiros em algum lugar e também convidar outras pessoas para trabalharem consigo no repositório. Um ótimo lugar para isso é o GitHub. Lembre-se de que já criámos um repositório no GitHub, então só precisamos conectar o repositório Git local ao GitHub. O comando git remote add faz exatamente isso. Digite o seguinte comando:

Nota: Antes de digitar o comando, vá à página do seu repositório no GitHub para encontrar o URL do repositório. Vai usá-lo no comando abaixo. Substitua https://github.com/username/repository_name.git pelo URL do seu GitHub.
```
git remote add origin https://github.com/username/repository_name.git
```
Isto cria um remote, ou conexão, chamado "origin", apontando para o repositório GitHub que criou anteriormente.
Enviar ficheiros locais para o GitHub. Até agora, criou uma conexão entre o repositório local e o repositório GitHub. Vamos enviar estes ficheiros para o GitHub com o seguinte comando git push, assim:

Nota: O nome da sua branch pode ser diferente por padrão de main.
```
git push -u origin main
```
Isto envia os seus commits na branch "main" para o GitHub.
Adicionar mais alterações. Se quiser continuar a fazer alterações e enviá-las para o GitHub, só precisará usar os seguintes três comandos:
```
git add .
git commit -m "type your commit message here"
git push
```
Dica: Também pode querer adotar um ficheiro .gitignore para evitar que ficheiros que não deseja rastrear apareçam no GitHub - como aquele ficheiro de notas que guarda na mesma pasta, mas que não tem lugar num repositório público. Pode encontrar modelos para ficheiros .gitignore em .gitignore templates.

Mensagens de Commit

Uma ótima linha de assunto para um commit no Git completa a seguinte frase:
Se aplicado, este commit irá .

Para o assunto, use o tempo presente e o modo imperativo: "alterar" em vez de "alterado" ou "altera".
Assim como no assunto, no corpo (opcional), também use o tempo presente e o modo imperativo. O corpo deve incluir a motivação para a alteração e contrastar isso com o comportamento anterior. Está a explicar o porquê, não o como.

✅ Dedique alguns minutos a explorar o GitHub. Consegue encontrar uma mensagem de commit realmente boa? E uma muito minimalista? Que informações acha que são mais importantes e úteis de transmitir numa mensagem de commit?

Tarefa: Colaborar

O principal motivo para colocar coisas no GitHub é tornar possível colaborar com outros programadores.

Trabalhar em Projetos com Outros

Veja o vídeo

No seu repositório, navegue até Insights > Community para ver como o seu projeto se compara aos padrões recomendados da comunidade.

Aqui estão algumas coisas que podem melhorar o seu repositório no GitHub:

Descrição. Adicionou uma descrição ao seu projeto?
README. Adicionou um README? O GitHub fornece orientações para escrever um README.
Diretrizes de Contribuição. O seu projeto tem diretrizes de contribuição?
Código de Conduta. Um Código de Conduta.
Licença. Talvez o mais importante, uma licença.

Todos estes recursos beneficiarão a integração de novos membros na equipa. E são tipicamente o tipo de coisas que novos contribuidores analisam antes mesmo de olhar para o seu código, para descobrir se o seu projeto é o lugar certo para eles investirem o seu tempo.

✅ Ficheiros README, embora levem tempo a preparar, são frequentemente negligenciados por mantenedores ocupados. Consegue encontrar um exemplo de um particularmente descritivo? Nota: existem algumas ferramentas para ajudar a criar bons READMEs que pode querer experimentar.

Tarefa: Fazer Merge de Código

Documentos de contribuição ajudam as pessoas a contribuir para o projeto. Explicam que tipos de contribuições está a procurar e como o processo funciona. Os contribuidores precisarão passar por uma série de etapas para poderem contribuir para o seu repositório no GitHub:

Fazer fork do seu repositório. Provavelmente, vai querer que as pessoas façam fork do seu projeto. Fazer fork significa criar uma réplica do seu repositório no perfil GitHub delas.
Clonar. A partir daí, elas irão clonar o projeto para o computador local.
Criar uma branch. Vai querer pedir-lhes que criem uma branch para o trabalho delas.
Focar a alteração numa área. Peça aos contribuidores para concentrarem as contribuições numa coisa de cada vez - assim, as chances de poder fazer merge do trabalho deles são maiores. Imagine que escrevem uma correção de bug, adicionam uma nova funcionalidade e atualizam vários testes - e se quiser implementar apenas 2 de 3 ou 1 de 3 alterações?

✅ Imagine uma situação em que as branches são particularmente críticas para escrever e enviar bom código. Que casos de uso consegue pensar?

Nota: Seja a mudança que quer ver no mundo e crie branches para o seu próprio trabalho também. Quaisquer commits que fizer serão feitos na branch em que está atualmente "checkout". Use git status para ver em que branch está.

Vamos passar por um fluxo de trabalho de contribuidor. Suponha que o contribuidor já fez fork e clone do repositório, então tem um repositório Git pronto para trabalhar no computador local:

Criar uma branch. Use o comando git branch para criar uma branch que conterá as alterações que pretende contribuir:
```
git branch [branch-name]
```
Mudar para a branch de trabalho. Mude para a branch especificada e atualize o diretório de trabalho com git switch:
```
git switch [branch-name]
```
Fazer o trabalho. Neste ponto, adicione as suas alterações. Não se esqueça de informar o Git com os seguintes comandos:
```
git add .
git commit -m "my changes"
```
Certifique-se de dar um bom nome ao seu commit, tanto para si como para o mantenedor do repositório que está a ajudar.
Combinar o seu trabalho com a branch main. Em algum momento, terá terminado o trabalho e quererá combiná-lo com o da branch main. A branch main pode ter mudado entretanto, então certifique-se de primeiro atualizá-la para a versão mais recente com os seguintes comandos:
```
git switch main
git pull
```
Neste ponto, certifique-se de que quaisquer conflitos, situações em que o Git não consegue facilmente combinar as alterações, aconteçam na sua branch de trabalho. Portanto, execute os seguintes comandos:
```
git switch [branch_name]
git merge main
```
Isto trará todas as alterações da main para a sua branch e, com sorte, poderá continuar. Se não, o VS Code indicará onde o Git está confuso e só precisará alterar os ficheiros afetados para indicar qual conteúdo é o mais preciso.
Enviar o seu trabalho para o GitHub. Enviar o seu trabalho para o GitHub significa duas coisas: enviar a sua branch para o seu repositório e depois abrir um PR (Pull Request).
```
git push --set-upstream origin [branch-name]
```
O comando acima cria a branch no seu repositório forkado.
Abrir um PR. Em seguida, abra um PR. Para isso, navegue até ao repositório forkado no GitHub. Verá uma indicação no GitHub perguntando se deseja criar um novo PR. Clique nisso e será levado para uma interface onde pode alterar o título da mensagem de commit, dar uma descrição mais adequada. Agora, o mantenedor do repositório que fez fork verá este PR e, dedos cruzados, apreciará e fará merge do seu PR. Agora é um contribuidor, yay :)
Limpar. É considerado uma boa prática limpar após fazer merge de um PR com sucesso. Deve limpar tanto a sua branch local quanto a branch que enviou para o GitHub. Primeiro, vamos eliminá-la localmente com o seguinte comando:
```
git branch -d [branch-name]
```

Certifique-se de aceder à página do GitHub para o repositório bifurcado a seguir e remover a branch remota que acabou de enviar para lá.

Pull request parece um termo estranho porque, na verdade, o que você quer é enviar as suas alterações para o projeto. Mas o responsável (proprietário do projeto) ou a equipa principal precisa considerar as suas alterações antes de as integrar na branch "main" do projeto, então, na verdade, está a solicitar uma decisão de alteração a um responsável.

Um pull request é o local onde se comparam e discutem as diferenças introduzidas numa branch, com revisões, comentários, testes integrados e mais. Um bom pull request segue, mais ou menos, as mesmas regras de uma mensagem de commit. Pode adicionar uma referência a um problema no rastreador de problemas, por exemplo, quando o seu trabalho resolve um problema. Isto é feito usando um # seguido do número do problema. Por exemplo, #97.

🤞Dedos cruzados para que todos os testes sejam aprovados e os responsáveis pelo projeto integrem as suas alterações no projeto🤞

Atualize a sua branch de trabalho local atual com todos os novos commits da branch remota correspondente no GitHub:

git pull

Como contribuir para open source

Primeiro, vamos encontrar um repositório (ou repo) no GitHub que seja do seu interesse e para o qual gostaria de contribuir com uma alteração. Vai querer copiar o conteúdo para a sua máquina.

✅ Uma boa forma de encontrar repositórios 'amigáveis para iniciantes' é procurar pela tag 'good-first-issue'.

Existem várias formas de copiar código. Uma delas é "clonar" o conteúdo do repositório, usando HTTPS, SSH ou a CLI (Interface de Linha de Comando) do GitHub.

Abra o seu terminal e clone o repositório assim: git clone https://github.com/ProjectURL

Para trabalhar no projeto, mude para a pasta correta: cd ProjectURL

Também pode abrir o projeto inteiro usando Codespaces, o editor de código integrado / ambiente de desenvolvimento na nuvem do GitHub, ou GitHub Desktop.

Por fim, pode descarregar o código numa pasta comprimida.

Algumas coisas interessantes sobre o GitHub

Pode marcar com estrela, seguir ou "bifurcar" qualquer repositório público no GitHub. Pode encontrar os seus repositórios marcados com estrela no menu suspenso no canto superior direito. É como guardar nos favoritos, mas para código.

Os projetos têm um rastreador de problemas, geralmente no GitHub na aba "Issues", a menos que seja indicado de outra forma, onde as pessoas discutem problemas relacionados ao projeto. E a aba Pull Requests é onde as pessoas discutem e revisam alterações que estão em progresso.

Os projetos também podem ter discussões em fóruns, listas de e-mails ou canais de chat como Slack, Discord ou IRC.

✅ Explore o seu novo repositório no GitHub e experimente algumas coisas, como editar configurações, adicionar informações ao repositório e criar um projeto (como um quadro Kanban). Há muito que pode fazer!

🚀 Desafio

Trabalhe em equipa com um amigo no código um do outro. Criem um projeto colaborativamente, bifurquem código, criem branches e integrem alterações.

Questionário Pós-Aula

Questionário pós-aula

Revisão e Autoestudo

Guia rápido de Git.

Pratique, pratique, pratique. O GitHub tem ótimos percursos de aprendizagem disponíveis em skills.github.com:

Primeira Semana no GitHub

Também encontrará cursos mais avançados.

Tarefa

Complete o curso Primeira Semana no GitHub

Aviso Legal:
Este documento foi traduzido utilizando o serviço de tradução por IA Co-op Translator. Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original no seu idioma nativo deve ser considerado a fonte autoritativa. Para informações críticas, recomenda-se uma tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes do uso desta tradução.

18 KiB Raw Permalink Blame History