Se você usa GitHub sem configurar uma chave SSH, não sabe o que está perdendo. Basta pensar que todo esse tempo que você passou inserindo o seu endereço de e-mail e senha no console toda vez que faz um commit poderia ter sido gasto programando.

Bem, não mais. Aqui está um guia rápido para gerar e configurar uma chave SSH no GitHub para que você nunca mais tenha que autenticar da maneira antiga.

Verificar a existência de uma chave SSH

Primeiro, verifique se você já gerou chaves SSH para a sua máquina. Abra um terminal e digite o seguinte comando:

ls -al ~/.ssh

Se você já gerou chaves SSH, você deve ver um resultado semelhante a este:

-rw-------  1 user_name user_name  1766 Jul  7  2018 id_rsa
-rw-r--r--  1 user_name user_name   414 Jul  7  2018 id_rsa.pub
-rw-------  1 user_name user_name 12892 Feb  5 18:39 known_hosts

Se suas chaves já existem, pule adiante para a seção Copiar a sua chave SSH pública abaixo.

Se você não vê nenhum resultado ou se aquele diretório não existe (você recebe uma mensagem No such file or directory), execute:

mkdir $HOME/.ssh

Em seguida, gere um novo conjunto de chaves com:

ssh-keygen -t rsa -b 4096 -C your@email.com

Agora, verifique se as suas chaves existem com o comando ls -al ~/.ssh e certifique-se de que o resultado seja similar ao listado acima.

Observação: as chaves SSH são sempre geradas como um par de chaves, uma pública (id_rsa.pub) e uma privada (id_rsa). É extremamente importante que você nunca revele sua chave privada e somente use sua chave pública para coisas como a autenticação no GitHub. Você pode ler mais sobre como os pares de chaves SSH/RSA funcionam aqui (texto em inglês).

Adicionar a chave SSH ao ssh-agent

O ssh-agent é um programa que começa quando você faz o login e armazena as suas chaves privadas. Para que funcione corretamente, ele precisa estar funcionando e ter uma cópia da sua chave privada.

Primeiro, certifique-se de que o ssh-agent está funcionando com:

eval "$(ssh-agent -s)" # for Mac and Linux

ou:

eval `ssh-agent -s`
ssh-agent -s # for Windows

Em seguida, adicione a sua chave privada ao ssh-agent com:

ssh-add ~/.ssh/id_rsa

Copiar a sua chave SSH pública

A seguir, você precisa copiar a sua chave SSH pública para a área de transferência.

Para Linux ou Mac, imprima o conteúdo da sua chave pública para o console com:

cat ~/.ssh/id_rsa.pub # Linux

Em seguida, selecione e copie o resultado.

Para o Windows, basta executar:

clip < ~/.ssh/id_rsa.pub # Windows

Adicionar a sua chave SSH pública ao GitHub

Vá para a sua página de configurações do GitHub e clique no botão "New SSH key":

Em seguida, dê à sua chave um título reconhecível e cole sua chave pública (id_rsa.pub):

Finalmente, teste a sua autenticação com:

ssh -T git@github.com

Se você seguiu todas estas etapas corretamente, você deve ver esta mensagem:

Hi your_user_name! You've successfully authenticated, but GitHub does not provide shell access.

Mais informações sobre o SSH (textos em inglês):

• Ultimate guide to SSH
• A top-down intro to SSH

A necessidade de gerenciar várias contas do GitHub na mesma máquina surge em algum momento para a maioria dos desenvolvedores. Sempre que eu tenho de trocar de computador ou quando preciso fazer um Git push com uma nova conta de trabalho, acabo tendo de navegar por todos os guias disponíveis on-line sobre algo que eu já fiz uma dezena de vezes.

Minha preguiça de não documentar o processo e minha incapacidade de lembrar do passo a passo me faz passar um bom tempo juntando as partes por toda a web e fazendo funcionar de algum modo.

Tenho certeza de que muitos de vocês já passaram por isso e que muitos mais estão somente esperando a próxima vez em que isso vai acontecer (eu mesmo incluído). Este artigo serve para ajudar a nós todos.

1. Geração das chaves SSH

Antes de gerar uma chave SSH, podemos verificar se temos chaves SSH existentes: ls -al ~/.ssh Esse comando listará todos os pares de chaves públicas e privadas, se eles existirem.

Se ~/.ssh/id_rsa estiver disponível, podemos reutilizá-lo. Do contrário, podemos gerar primeiro uma chave com o padrão ~/.ssh/id_rsa executando o seguinte comando:

ssh-keygen -t rsa

Ao sermos perguntados em que local devemos salvar as chaves, aceite o local padrão pressionando Enter. Uma chave privada e uma chave pública ~/.ssh/id_rsa.pub serão criadas no local padrão de ssh ~/.ssh/.

Vamos usar esse par de chaves padrão para nossa conta pessoal.

Para as contas de trabalho, criaremos chaves SSH diferentes. O código abaixo gerará as chaves SSH, salvando a chave pública com a tag "email@work_mail.com" em ~/.ssh/id_rsa_work_user1.pub

$ ssh-keygen -t rsa -C "email@work_mail.com" -f "id_rsa_work_user1"

Temos duas chaves diferentes criadas:

~/.ssh/id_rsa
~/.ssh/id_rsa_work_user1

2. Inclusão da nova chave SSH na conta do GitHub correspondente

Já temos prontas as chaves públicas SSH. Pediremos agora às nossas contas do GitHub para que confiem nas chaves que criamos. Isto serve para nos livrarmos da necessidade de digitar o nome de usuário e a senha cada vez que fizermos um Git push.

Copie a chave pública pbcopy < ~/.ssh/id_rsa.pub e entre em sua conta pessoal do GitHub:

1. Vá até Settings
2. Selecione SSH and GPG keys no menu à esquerda.
3. Clique em New SSH key, dê a ela um título adequado, e cole a chave na caixa que aparece
4. Clique em Add key — e pronto!

Para as contas de trabalho, use as chaves públicas correspondentes (pbcopy < ~/.ssh/id_rsa_work_user1.pub) e repita os passos acima nas contas de trabalho do GitHub.

3 . Registro das novas chaves SSH com o ssh-agent

Para usar as chaves, precisamos registrá-las com o ssh-agent em nossa máquina. Certifique-se de que o ssh-agent está em execução usando o comando eval "$(ssh-agent -s)".
Adicione as chaves ao ssh-agent assim:

ssh-add ~/.ssh/id_rsa
ssh-add ~/.ssh/id_rsa_work_user1

Faça com que o ssh-agent use as chaves SSH respectivas para os diferentes Hosts de SSH.

Esta é a parte crucial. Para ela, temos duas abordagens diferentes:

Usar o arquivo de configuração de SSH (Passo 4), e manter apenas uma chave SSH ativa no ssh-agent por vez (Passo 5).

4. Criar o arquivo de configuração de SSH

Aqui, estamos de fato adicionando regras de configuração de SSH para hosts diferentes, declarando que arquivo de identidade usar para cada domínio.

O arquivo de configuração de SSH estará disponível em ~/.ssh/config. Edite-o, se ele existir, ou crie-o, do contrário.

$ cd ~/.ssh/
$ touch config           // Cria o arquivo se ele não existir
$ code config            // Abre o arquivo no VS code, mas você pode usar qualquer editor

Faça as entradas de configuração para as contas relevantes do GitHub de maneira semelhante a que vemos abaixo em seu arquivo ~/.ssh/config:

# Conta pessoal, a configuração padrão
Host github.com
   HostName github.com
   User git
   IdentityFile ~/.ssh/id_rsa
   
# Conta de trabalho-1
Host github.com-work_user1    
   HostName github.com
   User git
   IdentityFile ~/.ssh/id_rsa_work_user1

"work_user1" é o id de usuário do GitHub para a conta de trabalho.

"github.com-work_user1" é uma notação usada para diferenciar as várias contas do Git. Você também pode usar a notação "work_user1.github.com". Lembre-se de ser consistente com a notação de nome de host que você usa. Isso é relevante ao clonar um repositório ou quando você define remote origin para um repositório local

A configuração acima pede ao ssh-agent para:

• Usar id_rsa como a chave para todo URL do Git que use @github.com
• Usar a chave id_rsa_work_user1 para qualquer URL do Git que use @github.com-work_user1

5. Uma chave SSH ativa no ssh-agent por vez

Esta abordagem não exige regras de configuração de SSH. Em vez disso, garantimos manualmente que o ssh-agent tenha apenas a chave relevante associada no momento de qualquer operação do Git.

ssh-add -l listará todas as chaves SSH associadas ao ssh-agent. Remova todas elas e adicione aquela que você usará.

Se for a da sua conta pessoal do Git:

$ ssh-add -D            //remove todas as entradas de ssh do ssh-agent
$ ssh-add ~/.ssh/id_rsa                 // Adiciona a chave ssh relevante

O ssh-agent agora tem a chave mapeada com a conta pessoal do GitHub. Podemos fazer um Git push para o repositório pessoal.

Para fazer o push para a conta de trabalho do GitHub, work-user1, mude a chave SSH mapeada com o ssh-agent removendo a chave existente e adicionando a chave SSH mapeada com a conta de trabalho do GitHub.

$ ssh-add -D
$ ssh-add ~/.ssh/id_rsa_work_user1

O ssh-agent agora tem a chave mapeada com a conta de trabalho do Github e você pode fazer um Git push para o repositório de trabalho. Isso, no entanto, exige um pouco de esforço manual.

Configuração do URL remoto do git para os repositórios locais

Ao termos o repositório local do Git clonado/criado, confira se o nome de usuário e o e-mail da configuração do Git são exatamente aqueles que você quer. O GitHub identifica o autor dos commits a partir do id de e-mail associado à descrição do commit.

Para listar o nome e o e-mail da configuração no diretório local do Git, digite os comando git config user.name e git config user.email. Se não forem encontrados, atualize-os de acordo.

git config user.name "User 1"   // Atualiza o nome de usuário do git config
git config user.email "user1@workMail.com"

6. Durante a clonagem dos repositórios

Observação: o passo 7 ajudará se tivermos o repositório já disponível no local.

Agora que as configurações estão prontas, podemos seguir em frente e clonar os repositórios correspondentes. Durante a clonagem, tome nota do que usarmos como nome de host e que usamos na configuração do SSH.

Os repositórios podem ser clonados usando o comando Git clone, fornecido pelo Git:

git clone git@github.com:personal_account_name/repo_name.git

O repositório de trabalho exigirá que se faça uma mudança com este comando:

git clone git@github.com-work_user1:work_user1/repo_name.git

Essa alteração é feita dependendo do nome do host definido na configuração do SSH. A string entre @ e : deve corresponder ao que fornecemos no arquivo de configuração do SSH.

7. Para repositórios locais existentes

Se já tivermos clonado o repositório:

Liste o Git remote do repositório, git remote -v

Verifique se o URL corresponde ao nosso host do GitHub a ser usado, ou atualize o URL de remote origin.

git remote set-url origin git@github.com-worker_user1:worker_user1/repo_name.git

Certifique de que a string entre @ e : corresponde ao Host que fornecemos na nossa configuração do SSH.

Se estiver criando um novo repositório no local:

Inicialize o Git na pasta git init do projeto.

Crie o novo repositório na conta do GitHub e adicione-o como o Git remote ao repositório local.

git remote add origin git@github.com-work_user1:work_user1/repo_name.git 

Certifique de que a string entre @ e : corresponde ao Host que fornecemos na nossa configuração do SSH.

Faça o push do commit inicial para o repositório do GitHub:

git add .
git commit -m "Initial commit"
git push -u origin master

Estamos prontos!

Adicionar ou atualizar o Git remote do diretório local do Git com o host adequado resolverá a seleção da chave de SSH correta para verificar nossa identidade com o GitHub. Quando tudo que vimos acima estiver pronto, nossas git operations funcionarão sem problemas.

Quando me apresentaram o GitHub, eu não tinha ideia do que era ou do que podia fazer. Cá entre nós, eu criei uma conta porque me disseram que todo desenvolvedor deveria ter uma para poder colocar seu código.

Na maior parte do meu tempo de iniciante, eu não fiz nada com minha conta. Depois, em função da minha paixão pela tecnologia, comecei a seguir outros desenvolvedores e a conferir o trabalho deles no GitHub. Foi quando percebi algo que eles tinham em comum: todos eles tinham projetos interessantes e contribuíam com o código aberto, mas os projetos deles também tinham arquivos README detalhados.

Foi assim que meu interesse sobre o que era o README cresceu. Então, eu decidi tentar e adicionei um aos meus projetos, também. Não vou mentir – fiz o arquivo na corrida e sem nenhum conhecimento de como ele deveria ser feito. Honestamente? Não saiu lá grande coisa. Você pode conferir ele AQUI.

Foi assim que ele permaneceu durante um bom tempo. Porém, com a prática e o aprendizado contínuo, consegui transformá-lo em uma documentação melhor, deixando-o ASSIM, o que melhorou o engajamento com o projeto e ajudou a fazer com que outros desenvolvedores se envolvessem.

Também é importante observar que um bom README ajudará você a se destacar no meio da grande massa de desenvolvedores que colocam seus trabalhos no GitHub.

Neste artigo, ensinarei mais a respeito do que é um arquivo README e sobre como escrever um. Primeiro, vamos entender o que o arquivo README representa.

O que é um arquivo README?

De modo simplificado, podemos descrever um arquivo README como um guia que dá aos usuários uma descrição detalhada do projeto em que você trabalhou.

Ele também pode ser descrito como uma documentação com diretrizes para usar em um projeto. Em geral, ele terá instruções sobre como instalar e executar o projeto.

Sendo um desenvolvedor, é essencial que você saiba como documentar seu projeto escrevendo um bom README, pois:

• É o primeiro arquivo que uma pessoa verá ao encontrar o projeto. Por isso, ele precisa ser breve, mas detalhado.
• Isso fará com que seu projeto se destaque dos outros. Claro, não se esqueça de fazer um bom projeto.
• Ele ajudará a priorizar as necessidades do projeto, quanto ao que precisa ser entregue e como fazer isso.
• Escrevê-lo vai melhorar suas habilidades de escrita. Como disse Friedrich Nietzsche:

Um bom escritor possui não só o seu próprio espírito, mas também o espírito de seus amigos.

Enquanto estiver trabalhando em um projeto, lembre-se de que você precisará que outros desenvolvedores entendam seu código e o que ele faz. Assim, associá-lo a um guia adicional será muito útil.

Por exemplo, o exemplo que eu compartilhei anteriormente do meu primeiro projeto não tem um bom README. Mesmo que o projeto fosse incrível, seria difícil para um iniciante entender o que exatamente era esperado deles ao clonarem meu repositório. Ele podia até mesmo ser o código de um vírus.

Com um projeto como esse no GitHub, não importa que ele seja fantástico, outros desenvolvedores não terão o interesse de trabalhar nele e de tentar desvendar o que ele é sem um bom README.

Agora, vamos dar uma olhada nesse projeto. Aqui, você consegue entender o que o projeto faz, de que se trata, e como começar se você precisar usá-lo ou se quiser contribuir com o projeto.

Perceba o poder de um README bem escrito e como ele pode mudar seu projeto.

Bem, vamos começar a escrever um para você, também.

Como escrever um bom README: um guia passo a passo

Algo muito importante que se deve perceber é que não há uma maneira "certa" de estruturar um bom README. Existe, no entanto, um jeito "errado", que é simplesmente não incluir um README.

Partindo da pesquisa e do estudo de vários arquivos README, certamente existem práticas recomendadas que encontramos. Isso é o que pretendo compartilhar aqui. Eu costumo dizer para mim mesmo:

Todo dia é dia de aprender.

Assim, ao progredir e avançar em sua carreira, você desenvolverá suas próprias ideias sobre o que torna um README bom e sobre como melhorá-lo. Talvez você até crie o seu próprio guia.

Antes de começarmos, é importante observar que, quando você está escrevendo o README do seu projeto, você deve poder responder o quê, o porquê e o como relativos ao projeto.

Veja aqui algumas perguntas orientadoras para ajudar você:

• Qual foi a sua motivação?
• Por que você criou esse projeto?
• Que problema ele resolve?
• O que você aprendeu?
• O que faz com que seu projeto se destaque?
  Se o seu projeto tem vários recursos, pense em adicionar uma seção "Recursos" e liste-os nela.

O que incluir no seu README

1. Título do projeto

Este é o nome do projeto. Ele descreve todo o projeto em uma frase e ajuda os outros a entenderem qual é o objetivo principal do projeto e seu intento.

2. Descrição do projeto

Este é um componente importante do projeto que muitos desenvolvedores iniciantes geralmente desconsideram.

A descrição é um aspecto extremamente importante do seu projeto. Uma descrição bem elaborada permite mostrar seu trabalho a outros desenvolvedores, assim como para empregadores em potencial.

A qualidade de uma descrição do README geralmente diferencia um projeto bom de um projeto ruim. Um projeto bom aproveita a descrição para explicar e exibir:

• O que o aplicativo faz,
• Por que foram utilizadas as tecnologias que estão no projeto,
• Quais foram os desafios enfrentados e os recursos que se espera implementar no futuro.

3. Sumário (opcional)

Se o seu README for muito extenso, é interessante adicionar um sumário para facilitar a navegação entre as diversas seções. Isso torna mais tranquila a movimentação dos leitores pelas várias partes do projeto.

4. Instalação e execução do projeto

Se estiver trabalhando em um projeto em que o usuário precisa instalá-lo ou rodá-lo localmente em uma máquina como um "POS", você deve incluir as etapas para a instalação do projeto e quais as dependências necessárias, se houver alguma.

Forneça uma descrição passo a passo de como fazer com que o ambiente de desenvolvimento esteja configurado e funcionando.

5. Uso do projeto

Dê instruções e exemplos para que os usuários/colaboradores consigam utilizar o projeto. Isso tornará mais fácil para eles caso encontrem algum problema – eles sempre terão um local de referência para aquilo que se espera do programa.

Você também pode fazer uso de auxílios visuais, incluindo materiais, como imagens, por exemplo, exibindo o projeto durante a execução, bem como a estrutura e os princípios de design usados no projeto.

Além disso, se o projeto exigir autenticação, como senhas ou nomes de usuário, esse é um bom local para incluir as credenciais.

6. Inclusão de créditos

Se você trabalhou no projeto em uma equipe ou em uma organização, liste os colaboradores/membros da equipe. Você também deve incluir links para os perfis do GitHub e para as redes sociais deles.

Se você também seguiu tutoriais ou consultou determinado material que possa ajudar o usuário a criar aquele projeto específico, inclua aqui os links para esse material.

Essa é apenas uma forma de mostrar sua gratidão e também de ajudar outras pessoas a obter uma cópia em primeira mão do projeto.

7. Inclusão de uma licença

Para a maioria dos arquivos README, essa geralmente é considerada a última parte. Ela permite que outros desenvolvedores saibam o que podem e o que não podem fazer com seu projeto.

Temos tipos diferentes de licenças, dependendo do tipo de projeto em que você estiver trabalhando. Conforme sua escolha, ela determinará as contribuições que seu projeto receberá.

A licença mais comum é a GPL, que permite que outras pessoas façam modificações em seu projeto e que o utilizem para fins comerciais. Se precisar de ajuda na seleção de uma licença, confira este link: https://choosealicense.com/ (em inglês).

Até aqui, tratamos dos requisitos mínimos para um bom README. Você talvez queira considerar adicionar as próximas seções para torná-lo ainda mais atrativo e interativo.

Seções adicionais do README

8. Badges

As badges (insígnias) não são necessárias, mas usá-las é um modo simples de permitir que os outros desenvolvedores saibam que você sabe o que está fazendo.

Uma seção como essa pode ser útil para fazer o vínculo com ferramentas importantes, além de mostrar algumas estatísticas a respeito do projeto, como o número de forks, colaboradores, issues abertas etc...

Abaixo vemos uma imagem de um de meus projetos que mostra como você pode utilizar as badges:

O lado bom desta seção é o fato de que ela se atualiza automaticamente.

Não sabe onde obter as badges? Confira as que estão hospedadas em shields.io. Eles têm muitas badges para ajudar você a começar. Você pode não entender o que elas representam agora, mas entenderá com o tempo.

9. Contribuição com o projeto

Essa parte será mais útil se você estiver desenvolvendo um projeto de código aberto que precisará da contribuição de outros desenvolvedores. Você pode querer adicionar diretrizes para que eles saibam como podem contribuir com seu projeto.

Também é importante garantir que a licença que você escolheu para um projeto de código aberto está correta, de maneira a evitar conflitos futuros. Adicionar diretrizes de contribuição representam um papel importante.

Algumas das diretrizes mais comuns incluem o código de conduta de colaboração e o guia do colaborador (em inglês). Esses documentos darão a você a ajuda necessária ao estabelecer as regras para o seu projeto.

10. Inclusão de testes

Faça aquele esforço a mais e escreva testes para o seu aplicativo. Depois, forneça exemplos de código e como executá-los.

Isso ajudará a mostrar que você conhece seu projeto e tem confiança de que ele funcionará sem problemas, o que dará confiança aos outros sobre ele, também.

Pontos a mais

Aqui vão uns pontos extras a serem observados no momento de escrever seu README:

• Mantenha-o atualizado - é uma prática recomendada garantir que seu arquivo esteja sempre atualizado. No caso de haver mudanças, não se esqueça de atualizar o arquivo quando necessário.
• Escolha um idioma - Somos todos de zonas diferentes e falamos idiomas diferentes. Isso, contudo, não significa que você precise traduzir seu código para o idioma local. Escrever seu README em inglês está ok, já que ele é um idioma aceito no mundo todo. Pode ser que você queira usar uma ferramenta de tradução aqui se o seu público alvo não estiver familiarizado com o inglês.

Conclusão

Pronto! Tudo o que você precisa para melhorar os seus arquivos README ou começar a escrevê-los está aqui.

Neste ponto, tenho a confiança de que você conseguirá adicionar um guia interativo e informativo ao seu próximo projeto ou até a um projeto existente e fará com que seu projeto se destaque.

Há várias ferramentas que você também pode usar para gerar automaticamente um arquivo README para seu projeto, mas é sempre uma boa prática tentar isso por conta própria antes de passar para a automação. Caso você queira conferir algumas delas, aqui temos algumas delas (em inglês):

• Make a README
• README Generator
• README

Se você leu até aqui, agradeço de coração. Se gostou do artigo e o achou útil, compartilhe-o para ajudar outros desenvolvedores a melhorarem seus projetos.

O autor gostaria de ver seu arquivo README recém-criado. Compartilhe com ele o link por meio de algum dos links abaixo:

Conecte-se com o autor pelo Twitter | YouTube | LinkedIn | GitHub

Compartilhe também sua opinião. Ela vale muito e o autor aprecia o seu feedback honesto!

Feliz programação! ❤