19 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 acompanhar o trabalho que faz na sua máquina
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, escreva: 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 escrever: 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).

Aceda a github.com e crie uma conta, se ainda não tiver uma, ou inicie sessão 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 na sua máquina local (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 acompanhar 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 é, quando escreve 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, no separador 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 acompanhar. Escreva:
```
cd [name of your folder]
```
Inicializar um repositório Git. No seu projeto, escreva:
```
git init
```
Verificar o estado. Para verificar o estado do seu repositório, escreva:
```
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 sobre quais ficheiros estão prontos para serem guardados no repositório ou têm alterações que talvez queira persistir.
Adicionar todos os ficheiros para acompanhamento
Isto também é chamado de preparar 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 acompanhados.
Adicionar ficheiros selecionados para acompanhamento
```
git add [file or folder name]
```
Isto permite adicionar apenas ficheiros selecionados à área de staging quando não quer 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 quer 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 acompanha 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 salvaguarda na história do seu repositório. Escreva 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 mais 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 na sua máquina, mas em algum momento vai querer ter um backup dos seus ficheiros em algum lugar e também convidar outras pessoas a trabalhar 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 de conectar o repositório Git local ao GitHub. O comando git remote add faz exatamente isso. Escreva o seguinte comando:

Nota: antes de escrever o comando, vá à página do 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 uma remota, ou conexão, chamada "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.
Para adicionar mais alterações. Se quiser continuar a fazer alterações e enviá-las para o GitHub, só precisará de 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 quer acompanhar 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 Git completa a seguinte frase: Se aplicada, esta alteração irá

Para o assunto, use o imperativo no presente: "alterar" em vez de "alterado" ou "altera". Tal como no assunto, no corpo (opcional) também use o imperativo no presente. 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

A principal razão para colocar coisas no GitHub foi 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 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 funciona o processo. Os contribuidores precisarão de passar por uma série de passos 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 a máquina 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 hipóteses de conseguir 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 ou puder 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 imaginar?

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 na máquina 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 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, termina o trabalho e quer 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, acontecem 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ó precisa de alterar os ficheiros afetados para indicar qual conteúdo é 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 de fork.
Abrir um PR. De seguida, quer abrir um PR. Faça isso navegando até ao repositório de fork no GitHub. Verá uma indicação no GitHub a perguntar se quer criar um novo PR; clique nisso e será levado para uma interface onde pode alterar o título da mensagem de commit e dar-lhe 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 boa prática limpar depois de um PR ser fundido com sucesso. Quer limpar tanto a sua branch local como a branch que enviou para o GitHub. Primeiro, elimine-a localmente com o seguinte comando:
```
git branch -d [branch-name]
```
Certifique-se de ir à página do repositório de fork no GitHub e remover a branch remota que acabou de enviar. Pull request parece um termo estranho porque, na verdade, o que você quer é enviar as suas alterações para o projeto. No entanto, o responsável pelo projeto (o proprietário) ou a equipa principal precisa avaliar as suas alterações antes de as integrar na branch "main" do projeto. Portanto, você está, na verdade, a solicitar uma decisão de alteração ao 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 aproximadamente 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 utilizando um # seguido do número do problema. Por exemplo, #97.

🤞Dedos cruzados para que todos os testes sejam aprovados e o(s) proprietário(s) do projeto integrem as suas alterações no projeto🤞

Atualize a sua branch local de trabalho 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 ao 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, utilizando HTTPS, SSH ou a CLI (Interface de Linha de Comando) do GitHub.

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

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

Também pode abrir o projeto inteiro utilizando 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 e/ou "forkar" 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", salvo indicação em contrário, 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 parceria com um amigo para colaborar no código um do outro. Crie um projeto colaborativo, faça fork do código, crie branches e integre alterações.

Questionário Pós-Aula

Questionário pós-aula

Revisão & Estudo Individual

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, é importante notar que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autoritária. Para informações críticas, recomenda-se a tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes da utilização desta tradução.

19 KiB Raw Permalink Blame History