Tutorial Git: criar um repositório no GitHub ou GitLab e cloná-lo

Um lembrete útil antes de começar, desenvolvido na introdução do tutorial: o Git corre na tua máquina, o GitHub e o GitLab são apenas alojadores de repositórios Git.

Há duas maneiras de chegar a um projeto seguido pelo Git e ligado ao GitHub ou ao GitLab, e a escolha depende apenas da ordem pela qual as coisas existem. Ou o repositório remoto já existe e vais buscá-lo: é clonar. Ou tens uma pasta na tua máquina e queres publicá-la: é inicializar e depois fazer push. Este capítulo trata os dois casos.

Criar o repositório remoto

No GitHub, o botão New a partir da página inicial, ou o endereço github.com/new. No GitLab, New project e depois Create blank project.

Há três decisões a tomar no momento da criação.

O nome. Passa a fazer parte do URL do repositório. Prefere minúsculas e hífenes, sem acentos nem espaços.

A visibilidade. Público significa legível por toda a gente, incluindo o histórico completo e, portanto, tudo aquilo de que tiveres feito commit por engano. Privado limita o acesso às pessoas que convidares. Na dúvida, começa em privado: passar de privado a público mais tarde é imediato, o contrário não apaga o que já foi copiado.

O ficheiro README. Marca a caixa apenas se contares clonar o repositório. Se já tens uma pasta para publicar, deixa o repositório completamente vazio, caso contrário terás de reconciliar dois históricos que não têm nada em comum.

Escolher entre o endereço SSH e o endereço HTTPS

Depois de criado o repositório, a página propõe-te um URL sob duas formas. Apontam para o mesmo repositório e só diferem no método de autenticação.

Repara bem na diferença de forma: o endereço SSH leva dois-pontos a seguir ao nome de anfitrião, não uma barra. E, sobretudo, o domínio muda consoante o serviço. Dar um URL github.com para um projeto alojado no GitLab é um erro de copiar-colar clássico.

Se puseste uma chave SSH no capítulo anterior, escolhe o endereço SSH: nunca mais te será pedido nada. O endereço HTTPS obriga a fornecer um token de acesso pessoal, que o gestor de credenciais pode memorizar.

Primeiro caso: o repositório existe, clona-lo

É a situação quando entras num projeto já lançado, ou quando criaste o repositório com um README.

git clone git@github.com:utilisateur/projet.git

O Git cria uma pasta projet no diretório atual, descarrega para lá a totalidade do histórico e regista o repositório remoto sob o nome origin. Para escolheres outro nome de pasta, acrescenta-o como segundo argumento:

git clone git@github.com:utilisateur/projet.git mon-dossier

Verifica o que obtiveste:

cd projet
git remote -v
git branch --show-current

origin	https://github.com/git/git.git (fetch)
origin	https://github.com/git/git.git (push)
master

Duas observações sobre esta saída. O origin aparece duas vezes porque o Git distingue o endereço de leitura do endereço de escrita, quase sempre idênticos. E a branch chama-se aqui master porque esse é o nome da branch por omissão do repositório clonado: a clonagem retoma o nome do servidor e ignora por completo a tua definição init.defaultBranch, que só diz respeito aos repositórios que tu próprio crias.

Segundo caso: a pasta existe, publica-la

É a situação quando começaste a trabalhar antes de pensares no Git. Coloca-te na pasta do projeto.

cd ~/projets/ma-boutique
git init

Initialized empty Git repository in /root/a2/.git/

O Git acabou de criar uma subpasta .git que contém todo o histórico. Apagá-la equivaleria a apagar o controlo de versões, o resto dos teus ficheiros fica intacto.

Regista a seguir um primeiro commit, sem o qual não há nada para publicar:

git add .
git commit -m "Premier commit"

Declara agora o repositório remoto e faz push:

git remote add origin git@github.com:utilisateur/ma-boutique.git
git branch -M main
git push -u origin main

Estas três linhas merecem uma explicação, porque são muitas vezes copiadas sem serem compreendidas.

O git remote add origin associa o nome curto origin ao URL do repositório. O origin não tem nada de mágico, é uma convenção, podias chamar-lhe outra coisa, mas ninguém o faz.

O git branch -M main renomeia a branch atual para main. O -M maiúsculo força a mudança de nome mesmo que já exista uma branch main. Esta linha é inútil se definiste o init.defaultBranch no capítulo anterior, mas não faz mal nenhum.

O git push -u origin main envia a branch e, graças ao -u, memoriza a ligação entre a tua branch local e a do servidor. É essa ligação que permite escrever depois apenas git push e git pull. Sem ela, o Git para-te:

fatal: No configured push destination.
Either specify the URL from the command-line or configure a remote repository using

    git remote add <name> <url>

and then push using the remote name

    git push <name>

To push to multiple remotes at once, configure a remote group using

    git config remotes.<groupname> "<remote1> <remote2>"

and then push using the group name

    git push <groupname>

A armadilha do README marcado

Se criaste o repositório remoto com um README quando a tua pasta local já tinha commits, cada lado tem o seu próprio primeiro commit, sem nenhum antepassado comum. O Git recusa-se então a reuni-los:

fatal: refusing to merge unrelated histories

A solução é pedir-lho explicitamente, uma única vez:

git pull origin main --allow-unrelated-histories

Merge made by the 'ort' strategy.
 README.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 README.md

Os dois históricos ficam reunidos por um commit de merge e o README junta-se aos teus ficheiros. Podes depois fazer push normalmente.

Gerir os repositórios remotos

Alguns comandos a conhecer para a continuação.

git remote -v                                    # listar os repositórios remotos
git remote set-url origin git@github.com:u/p.git # mudar o URL, por exemplo passar de HTTPS para SSH
git remote rename origin upstream                # renomear
git remote remove origin                         # desassociar

O git remote set-url é o comando a reter: é ele que repara um repositório clonado em HTTPS que queres passar para SSH, sem teres de clonar tudo outra vez.

Um repositório local pode viver sem servidor

Nada te obriga a publicar. Um git init seguido de commits funciona perfeitamente numa pasta que nunca vai sair da tua máquina, e já ficas com o histórico e com a possibilidade de voltar atrás. O repositório remoto traz três coisas: uma cópia de segurança fora do teu disco, um ponto de partilha com outras pessoas e o acesso às ferramentas do alojador.

O teu projeto está montado. O capítulo seguinte passa aos comandos do trabalho diário e à forma de anular um erro.