Exibir código-fonte para Github Desktop


==Instalação do Github Desktop==
Antes da instalação, será necessário criar uma conta no Github.
Agora, para instalar o Github Desktop, acesse a página:
:desktop . github . com (sem os espaços entre os pontos),
baixe o instalador e instale.

== Repositórios ==
Repositório é um local central de armazenamento de dados. Eles são usados em conjunto com [[ferramentas de versionamento]] para poder facilmente acessar os dados de qualquer versão do projeto.

=== Tipos de Repositório ===
O Git usa um sistema de versionamento ''Distribuído'', que sua estrutura utiliza de dois tipos diferentes de repositórios:

*Repositório Local
O repositório local é a cópia do repositório remoto que cada usuário do projeto têm. Esse ambiente distribuído têm o intuito de permitir com que cada usuário faça qualquer alteração sem que isso afete os outros usuários. Essas alterações então podem ser enviadas para o repositório remoto. Este processo pode gerar [[#Gerenciando Conflitos de Merge|conflitos]], caso a versão dos arquivos do repositório local esteja muito desatualizada da versão atual do repositório remoto. Por causa disso, é recomendável sincronizar as duas versões frequentemente.


*Repositório Remoto
O repositório remoto serve como servidor do projeto, armazenando os arquivos que irão ser usados pelos repositórios locais. Mudanças feitas nele (geralmente pelo envio de alterações vindas de algum repositório local) afeta todos os usuários, que precisarão sincronizar seus repositórios locais para ter a versão mais recente dos dados. Este processo pode também gerar [[#Gerenciando Conflitos de Merge|erros de conflito]] caso vários usuários mandem modificações das mesmas partes de um dado arquivos. Por causa disso, é recomendado que as tarefas dadas as usuários envolvam arquivos diferentes para que conflitos não ocorram frequentemente.

=== Usando repositórios com o Github Desktop ===
Usando o Github Desktop, existem três maneiras de inicializar um Repositório: 
É possível criar um repositório local novo(e, portanto, um novo projeto),clonar algum projeto que já esteja no Github (ou seja, fazer uma cópia do repositório remoto para o local), ou apenas adicionar um repositório existente no computador do usuário(apontando qual pasta ele está).

====Criando um repositório local====

Vá em ''File'', e em ''New Repository''. Será aberto uma nova tela.
[[Arquivo:New Repository.png]]

[[Arquivo:Create a new repository.png|border]]

Nesta tela, terão os seguintes parâmetros de criação:
*Nome, descrição, e diretório local: auto-explicativos.
*Inicialize esse repositório com um README: Cria um arquivo readme no projeto. Este arquivo é a primeira coisa a ser vista ao acessar um projeto no github. Por causa disso ele normalmente é usado como uma apresentação ou guia do projeto.
*Git ignore: permite escolher qual modelo de arquivo .gitgnore quer usar. Este arquivo serve para configurar que o git ignore certos tipos de arquivos. Cada modelo é feito para uma linguagem específica. O arquivo pode também ser manualmente  criado e/ou editado pelo usuário.
*Licença: define o tipo de licença que o projeto usará.

====Adicionar um repositório local====
Caso tenha um repositório local já criado na sua máquina, é possível adicionar ele ao Github Desktop. <br>
Para isso, vá ao menu no canto superior direito, clique em ''file'', e em ''Add local repository''.

[[Arquivo:Opção add local repository.png|border]]

Nesta nova tela, adicione o caminho da pasta onde o repositório se encontra

[[Arquivo:Escolha Add local repository.png]]
----

====Clonar um repositório remoto====
Existem duas maneiras de clonar um repositório:

=====Usando o Github Desktop=====
Vá em Files -> Clone repository
 
[[Arquivo:Clone repository.png|border]]

A aba ''Github.com'' permite rapidamente clonar algum repositório do usuário, enquanto a aba ''URL'' permite clonar qualquer repositório disponível usando a sua url.
 
[[Arquivo:Clonando o Repositorio.png|border]]

=====Usando o Delphi=====
A IDE do Delphi têm suporte ao git, e, consequentemente, também tem suporte a clonagem de repositórios. Mas antes de acessar o projeto, é necessário configurar o git no Delphi.<br>
Vá em Tools -> Version Control - > Git. <br> Nesta  tela, coloque, no campo ''git executable'', o caminho até o executável do git. E em ''Authorization'', digite o nome de usuário e email usado no github.

[[Arquivo:Configuração do Git - Delphi.png]]

Agora será possível acessar a integração com o Git. Na tela principal clique em ''File'', e em ''Open From Version Control''.

[[Arquivo:Open From Version Control.png]]

Na tela aberta,escolha o git.

[[Arquivo:Select version control.png]]

Em ''Source'' adicione o link do projeto ('''SEM''' o ".git" no final), e em ''Destination'' adicione a pasta onde o projeto ficará.

[[Arquivo:Clonar Projeto Delphi.png]]

===Criar e conectar um repositório remoto===
Caso tenha criado um repositório local novo, será necessário, antes de qualquer coisa, publicar um repositório remoto correspondente. Este passo não é necessário caso tenha clonado um repositório, ou adicionado um repositório que já tenha a parte remota.

Para publicar o repositório, clique no botão "Publish repository" no canto superior da tela.
[[Arquivo:Publish repository.png]]

Caso ainda não tenha feito, será necessário logar com a sua conta do Github.

[[Arquivo:Sign In.png]]

No campo ''Name'', digite o nome do repositório remoto. Em ''Description'' adicione a descrição do projeto. Cheque a opção ''Keep this code private'' caso queira um repositório remoto privado.

[[Arquivo:Publish repository - Create.png|border]]

===Rastreando arquivos no repositório git===

Para poder versionar(ou,"commitar") um arquivo ele precisa primeiro ser rastreado pelo git. O rastreamento(também chamado de "tracking") ocorre sempre que um arquivo, na pasta do repositório local, é adicionado ou modificado. Existem três maneiras principais:

(Observação:'''Nenhum desses métodos usam diretamente a interface gráfica do Github Desktop''', pois o programa, por si só, não têm suporte a criar e editar arquivos.)

[[Arquivo:Opções - Acessar Arquivos.png]]



;N° 1 - Acessar diretamente a pasta
 
:Clique no botão ''Show in Explorer'' para acessar a pasta do repositório local (ou acesse diretamente usando o explorador de arquivos). Nesta pasta, arquivos podem ser preparados para o rastreamento usando a maneira convencional do windows (clicando no botão direito, e indo em "novo"), ou simplesmente arrastando algum arquivo para a pasta. 

[[Arquivo:Criar novo arquivo.png]]


;N° 2 - Usar um editor de texto:
 
:Clicar no botão ''Open the repository in you external editor'' abrirá a pasta do repositório local no editor de texto de escolha (Nota: o editor precisa ter suporte ao git. Qual editor será usado pode ser mudado nas configurações). Arquivos então podem ser criados ou adicionados usando as maneiras convencionais do editor.  

[[Arquivo:Criar arquivo Visual Code.png]]<br>
(Exemplo de como criar um arquivo no Visual Code Studio)


;N° 3 - Usar uma IDE

:Qualquer programa que crie e edite arquivos pode ser usado, como ambientes de desenvolvimento. Portanto, o Delphi pode ser usado também. Para usar, cloneie um repositório remoto com o [[#Usando o Delphi|controle de versão intregado do Delphi]], ou apenas crie um projeto Delphi no repositório local. Agora, qualquer arquivo que for criado nesta pasta ou for editado poderá ser rastreado pelo git.

== Versionando arquivos com o Commit ==
Commit é um retrato do estado de um ou mais arquivos do repositório, ou seja, cada commit cria uma versão nova dos arquivos commitados. No primeiro commit do arquivo, o git armazena completamente o arquivo; Nos próximos commits, o git apenas vai armazenar os dados que são diferentes, e usar o commit anterior como base para construir o arquivo inteiro.

===Commitando arquivos===
Após um arquivo ser adicionado ou modificado no repositório, ele automaticamente aparecerá no lado superior esquerdo da tela do Github Desktop.
 
[[Arquivo:Arquivo commitado.png|border]]

Para selecionar quais arquivos serão commitados, clique no cheque ao lado do arquivo desejado.

Quando estiver pronto para criar o commit, digite o título e descrição do commit nos campos localizados no lado inferior esquerdo da tela, e clique então no botão “commit”.<br> 
OBSERVAÇÃO: O título de um Commit é obrigatório
 
[[Arquivo:Commitando arquivo.png|border]]

===Estado dos arquivos===
Todos os arquivos num repositório podem estar em quatro tipo de estados:

[[Arquivo:Estado Arquivos.png|border]]


*Untracked
O estado Untracked (Tradução:"Não-rastreados") são arquivos que foram adicionados no repositório, ou existiam na pasta antes da sua criação, e ainda não tiveram alguma interação com o git. Como o nome indica, este é o único estado onde os arquivos não são rastreados pelo git. 

<br>
*Staged
São arquivos, dos estados ''Untracked'' e ''Modified'', que foram colocados em uma área de preparação, chamada de ''staging'', para que possam ser commitados.<br>
É possível regredir arquivos deste estado para o seu estado anterior.

<br>
*Commited
São arquivos que foram ''Commitados'', ou seja, que seus dados foram versionados. Neste estado, os arquivos não podem mais regredir para estados anteriores, podendo apenas ficar no mesmo estado ou mudar para o estado Modified. Este é o estado principal do ciclo de vida do arquivo, e normalmente onde ele ficará por mais tempo entre todos os estados.

<br>
*Modified
Estado de arquivos commitados que foram posteriormente modificados pelo usuário.<br>
Para que possam novamente ser commitados (e então ser versionados), é necessário readicionar os arquivos modificados ao estado de staging.

===Histórico de commits===
O histórico de commits pode ser acessado ao clicar na aba “History”
 
[[Arquivo:Acessar Histórico.png]]

O histórico contém todos os commits daquele dado [[#Branchs|branch]], assim como os seus dados (descrição, arquivos commitados, hash do commit, número de mudanças, entre outros).

[[Arquivo:Histórico.png]]

== Transferindo dados entre o repositório local e remoto ==
Existem dois comandos no Git para a transferência de dados entre os dois tipos de repositório: Push, e Pull.
===Git push ===
(Atalho: Ctrl + P)
 
Push é o comando que envia todos os commits locais (que ainda não foram enviados) para o repositório remoto.
Para usar o Push, apenas clique no botão no canto superior da tela.

[[Arquivo:Git push.png]]


O Push não irá funcionar caso o repositório remoto tenha sido atualizado. Isso acontece para que [[#Gerenciando Conflitos de Merge|conflitos de merge]] sejam minimizados.<br>
Nestes casos, é necessário atualizar o repositório local primeiro e tentar novamente. 

[[Arquivo:Newer commits on remote.png]]

====Pull request====
[!] TO-DO

===Git pull===

(Atalho: Ctrl + Shift + P)
 
Git Pull é uma junção de sub-comandos, que juntos são o meio de atualizar e sincronizar o repositório local com o repositório remoto.<br>
O uso do ''Pull'' é simplificado no Github Desktop. Primeiramente, para verificar se o repositório remoto teve alguma atualização, use o comando ''Fetch'':

[[Arquivo:Git pull.png]]

OBSERVAÇÃO:Uma boa prática é constantemente rodar o Fetch antes de começar a trabalhar em um alguma nova feature, para sempre estar o mais atualizado possível antes de começar a fazer commits.


Depois de rodar o Fetch, o comando Push será disponível caso tenha sido encontrado alguma atualização no repositório remoto. Ao clicar nele, todas as atualizações serão lançadas no repositório local, o que automaticamente atualiza cada branch desatualizado do projeto.

[[Arquivo:Git Fetch.png]]

OBSERVAÇÃO:Ambos os botões, para push e fetch, se encontram no mesmo lugar da tela.

==Branchs==
Branches ("bifurcações") são divergências da linha principal do desenvolvimento.Isso permite ao usuário criar uma versão do projeto onde modificações incompletas ou instáveis podem ser adicionadas, sem que a linha principal(chamada de Branch "master") seja afetada.<br>Quando um branch é criado, ele necessita herdar,de algum outro branch, a linha de commits e histórico do projeto. O branch que está sendo atualmente usado pelo usuário é chamado de HEAD.

===Criando um Branch===
Clique na tela de seleção de branches, e clique então no botão “New Branch”.

[[Arquivo:New branch.png|border]]

Digite um nome ao branch, e então clique em “Create Branch”

[[Arquivo:Create branch.png|border]]

Crie um novo commit neste branch, e mude para o branch master. Para fazer isso, clique no botão dos branches e em Master.

[[Arquivo:Trocando de Branches.png|border]]

Como pode ser visto, commits criados em um branch apenas são pertinentes a aquele branch.

[[Arquivo:Commit branch.png|border]]

[[Arquivo:Branch Master sem commit.png|border]]

===Unindo Branches===
Durante os projetos, haverá momentos onde há uma necessidade de unir o conteúdo de certos branches. Existem duas maneiras principais de fazer isso: Merge, e Rebase.<br>
Para ajudar com o entendimento da explicação, será usado o seguinte exemplo para ilustrar como que ambos métodos funcionam:

[[Arquivo:Dois Branches.png]]


OBSERVAÇÃO: Unir um branch com o outro não irá automaticamente destruir ele. Isso têm que ser feito manualmente.
====Merge====
Merge é  tipo de união de branches mais comum. Ele cria um novo commit em um dos branches (neste exemplo, é o ''master''), que une ambos os branches, e seus históricos, sem perder a sua integridade. Entretanto, por conservar o histórico tão detalhadamente, quando há o merge de vários branches o gráfico e histórico podem se tornar bem confuso. Merges são fáceis de desfazer, caso seja necessário, e de lidar com conflitos de merge.

[[Arquivo:Exemplo Merge.png|x500px]]


Para fazer um Merge no Github Desktop, em primeiro lugar é necessário mudar para '''o branch que receberá os commits'''. Agora, abra a lista dos branches e clique em ''Choose a branch to merge into master''. Esta opção também é acessível com o  atalho <code>Ctrl+Shift+M</code>.

[[Arquivo:Opção Merge.png|border]]


Agora, escolha o branch de onde os dados serão copiados, e clique no botão para finalizar.

[[Arquivo:Confirmar Merge.png]]
----

====Rebase====
Diferente do Merge, o ''Rebase'' funciona pegando os commits de um branch(neste exemplo, ''feature''), e adicionando em cima dos commits do branch de destino(''Master''). Este processo cria um gráfico e histórico mais limpo, ao custo da integridade do histórico, que tem que ser reescrito para acomodar a adição dos commits. O Rebase também é mais difícil de reverter, ou resolver conflitos, do que o Merge.

[[Arquivo:Exemplo Rebase.png|x500px]]


Para fazer um Rebase no Desktop, entre no '''branch que enviará os commits'''. Agora, vá na aba ''Branch'' do menu, e escolha ''Rebase current Branch'', ou acesse diretamente com a tecla de atalho <code>Ctrl+Shift+E</code>.

[[Arquivo:Opção Rebase.png]]

Nesta nova tela, escolha o branch que receberá os commits e clique no botão para finalizar.

[[Arquivo:Confirmar Rebase 2.png]]

== Gerenciando Conflitos de Merge ==
Durante um Merge/Rebase ou Push/Pull, o git normalmente se encontra em situações onde várias modificações são adicionadas ao mesmo arquivo. Na maioria dos casos, o git consegue resolver esses conflitos analisando o histórico do repositório e verificando se as modificações são compatíveis (Exemplo: Um arquivo está recebendo modificações para linhas diferentes, e portanto não gera conflito). Entretanto, existem certos casos onde as modificações conflitam umas com as outras, gerando um Conflito de Merge.

Conflitos de Merge é quando as modificações para um dado arquivo se sobrepõem. Diferente do que o nome pode indicar, Conflitos de Merge pode tanto acontecer entre o repositório local e remoto(nas ações de Push, Pull e Pull request), quanto entre dois ou mais branches(ao usar o merge e rebase).<br>
Para resolver um conflito de merge, '''é necessário manualmente escolher''' qual das duas versões (ou uma combinação de ambas) será usada. Não existe um meio automático de resolvê-lo. 

=== Exemplos de situações que geram um  Conflito de Merge ===
;Exemplo com branches: 
:Crie um repositório novo, e adicione no master um arquivo "Texto.txt" com o texto "Branch usado: ", e dê um commit nele. Agora, crie dois branches baseados no master, "Branch1" e "Branch2". Para cada um, edite o arquivo Texto e adicione o nome do branch ao final da linha, e dê um commit para cada. Agora, quando uma operação de merge ou rebase ser feita com os dois branches, ocorrerá um Conflito de Merge, já que as duas versões do arquivo têm a mesma linha mudada.
  
;Exemplo com Push/Pull:
:Crie o mesmo arquivo no master, mas agora, em vez de criar branches, apenas mude o valor do arquivo e dê um commit. Agora, vá no repositório remoto com o Github(ou apenas mude de usuário no Desktop) e modifique o valor da linha do arquivo de texto e dê um commit. Volte ao Github Desktop e tente dar push. Você será notificado de que é necessário dar um pull primeiro, que caso feito acontecerá um conflito de merge. 

=== Resolvendo o Conflito ===
Em ambos os casos, quando o usuário tentar a fazer a ação, uma mensagem semelhante a essa aparecerá:


[[Arquivo:Merge Conflict de Branch.png|border]]


Na próxima tela, será pedido para resolver os conflitos de merge, ou simplesmente cancelar o merge. Você pode escolher resolver o conflito usando a linha de comando, editando manualmente o arquivo ou usando algum editor de texto com compatibilidade com o Git(como o vscode).

[[Arquivo:Tela de Conflitos do Branch.png]]

Ao abrir o arquivo conflitante com um editor de texto, verá uma tela parecida com a de baixo.

[[Arquivo:Gerenciamento de Conflitos.png]]

Para resolver o conflito, apenas apague os caracteres adicionados pelo git (neste caso, seria necessário remover as linhas 1,3,5) e junte ou elimine as linhas conflitantes.
No caso de editores de texto como o visual Studio Code, existem também atalhos, localizados acima das linhas marcadas, que seu uso é de substituir certas ações manuais:
* Accept Current Changes: Aceita as modificações da versão "Current"(a verde), e descarta a versão "Incoming"(a azul).
* Accept Incoming Changes: Aceita as modificações da versão "Incoming"(a azul), e descarta a versão "Current"(a verde).
* Accept Both Changes: Aceita ambas as modificações.
* Compare Changes: Abre uma nova aba, onde compara as diferencias entre os dois aquivos, como mostrado na imagem abaixo:
[[Arquivo:Comparando Versões.png|1100px]]


Após todas as modificações serem feitas, salve e feche o arquivo. Agora, retorne ao Github Desktop, cheque se o conflito foi resolvido e clique no botão de confirmar para que a ação iniciada (push/pull, ou merge/rebase) possa ser finalizada.

[[Arquivo:Conflito Resolvido.png|border]]<br>
OBSERVAÇÃO: Caso houver vários conflitos de merge após uma operação, o processo de editar o arquivo e mudar as linhas conflitantes terá que ser feito novamente para cada conflito.

==Git stash e o armazenamento temporário==
Normalmente, se um usuário do git tentasse mudar de branch enquanto ainda houvesse arquivos a ser commitados, os arquivos seriam descartados. Felizmente, o Github Desktop impede essa situação, forçando o usuário a escolher entre duas opções: Mover os arquivos para o outro branch, ou usar o stash.

o git stash guarda os arquivos a ser commitados em um armazenamento temporário, permitindo o usuário a fazer ações como mudar de branches sem haver algum problema. Para usar o git stash, clique na primeira opção; Para levar os arquivos para o branch de destino, escolha a segunda opção.


[[Arquivo:Git stash.png|border]]


Agora, quando retornar ao branch original, para retirar os arquivos do armazenamento, clique no botão ''View Stash''

[[Arquivo:Stash 1.png|border]]


ou acesse diretamente clicando no botão ''Stashed Changes'', localizado acima do área de commit.

[[Arquivo:Stash 2.png|border]]


Agora, nesta nova tela, clique em ''Restore'' para restaurar os arquivos a área de staging

[[Arquivo:Stash 3.png|border]]

==Como adicionar novos usuários ao repositório==
Entre no respositório no github, e vá em Settings -> Collaborators. Nessa tela, é possível pesquisar por colaboradores para adicionar no projeto.

== Demonstração do processo padrão de uso do Github Desktop ==
Neste tópico, sera demonstrado o passo a passo do fluxo de trabalho ao utilizar o git:

*;Primeiro passo - Receber atualizações
Antes de começar a programar, é uma boa prática verificar se há alguma atualização no repositório local, e [[#Git pull | baixar]]-las caso tenha.<br>
OBSERVAÇÃO:Caso for usar um branch para o versionamento, e a etapa anterior já foi feita, atualize tal branch com os dados do master. Este processo pode ser feito no menu em Branch, e em ''Update from Default Branch''.

[[Arquivo:Update from default branch.png]]


*;Segundo passo - modificar e versionar
Agora, depois de verificar que esteja no branch correto, comece a programar as funcionalidades desejadas.Sempre que estiver no ponto onde alguma parte de uma funcionalidade estiver completa e estável, crie um [[#Commitando arquivos| commit]] com os arquivos que compõem esta parte.

*;Terceiro passo - Enviar atualizações 
Depois de alguns commits, clique no botão de push para os enviar ao repositório remoto. Assim como o pull, é uma boa prática não demorar muito para dar um push, ou ter commits demais para um único push, pois esses comportamentos ajudam na geração de [[#Gerenciando Conflitos de Merge| conflitos de merge]].

*;Quarto passo(opcional) - Unir branches e atualizar o remoto
Em certos casos será necessário também o merge ou rebase de certos branches após o push. Por exemplo, em um dos nossos projetos, todos os desenvolvedores tem que [[#Unindo Branches| unir o seu branch]] com o branch Homologação, utilizando de merge. Depois é necessário atualizar o branch remoto do Homologação com um push.

[[Category:AnDes_Web]]