Magic xpa Integrado ao GIT

Vamos ver nesta publicação como utilizar o GIT como controle de versão e desenvolvimento concorrente, de projetos Magic xpa.

Inicialmente, vamos alinhar as expectativas e destacar que esta publicação não visa explicar ou ensinar o funcionamento do GIT. Este é um conhecimento prévio necessário.

Visa, no entanto, mostrar como integrá-lo ao Magic xpa.

Esta postagem também foca nos desenvolvedores (DEVs) que já utilizam o Magic xpa com algum outro SCM (VSS, CVS, TFS…), destacando principalmente nas diferenças. Não serão abordados recursos avançados do GIT, como os múltiplos branches por exemplo.

E também, embora existam outras (boas) opções para repositório central (GitLab, AzureDevOps, BitBucket), esta publicação será baseada no GitHub.

Por fim, este post abordará o funcionamento da integração entre GIT e Magic xpa da versão 3.1 até a 4.6 do Magic.

*Nota: Houve algumas pequenas mudanças nesta integração a partir da versão 4.7, mas isso será abordado em publicação futura.

 

Pré-Requisitos

 

Estes são os preparativos para começar a integração:

• Instalar o Git for Windows (https://gitforwindows.org/), na máquina de cada DEV
• Instalar o Tortoise for Git (https://tortoisegit.org/), na máquina de cada DEV
• Instalar o Compare & MERGE do Magic xpa (https://downloads.magicsoftware.com/MagicScripts/MGrqispi.dll?APPNAME=Downloads&PRGNAME=Login&ARGUMENTS=-A,-A), última versão que estiver disponível no site, na máquina de cada DEV
• Cada DEV da equipe deve atribuir a si um número exclusivo, entre 0 e 31, que será o seu “VersionControlID“. Ex:
  • DEV Juan = 1
  • DEV Marina = 2
  • DEV Carlos = 3
  • DEV ??? = ‘n’ (até 31)
• Cada DEV da equipe deve usar um INI de Diferença (adendo) no atalho do seu Magic xpa Studio, com os ajustes abaixo:

  • /[MAGIC_ENV]PathToGit = *<pasta instalação GIT>\bin\git.exe

  • /[MAGIC_ENV]PathToGitPlugin = *<pasta instalação TortoiseGit>\bin\TortoiseGitProc.exe

  • /[MAGIC_ENV]VersionControlID = <Id Exclusivo, ex: 1, cfe. explicado acima>

  • /[MAGIC_ENV]SourceControlPlugin = G

  • /[MAGIC_SPECIALS]SpecialMultipleCheckout = Y

• Ter uma conta no GitHub e criar nele um repositório para o seu projeto Magic xpa . Cada projeto Magic xpa necessita do seu próprio repositório (1:1), e cada repositório tem a sua própria url GIT. Ex:

 

O GitHub será o repositório central dos projetos Magic xpa, assim que como é o TFS/VSS/CVS Server, porém ele fica na internet (e não na intranet).

Por isso, além da conectividade internet ser um pré-requisito, você provavelmente vai querer criar seus repositórios como “privados”.

 

Com os pré-requistos resolvidos, vamos ver as principais operações com desenvolvimento concorrente no Magic xpa + GIT.

Lembrando que o objetivo aqui é comparar o antes (TFS/VSS/CVS) com o depois (GIT).

 

Criando um Projeto NOVO

 

 

O Magic xpa Studio cria o projeto normalmente, já com o seu REPO LOCAL (subpasta .git).

Com o menu de contexto do Windows Explorer, vamos escolher a opção “Open GIT Bash Here” (ela existe por causa das instalações dos pré-requisitos):

 

Neste shell (console bash), vamos alterar o nome da branch git principal, de “master” para “main“:

git branch -m master main

 

e vincular o REPO LOCAL ao REPO REMOTO (GitHub):

git remote add -m main origin https://github.com/desenvmagicbr/IntegracaoMagicxpaGit.git <-- URL deste exemplo

git push --set-upstream origin main

 

Pronto. Agora é possível levar alterações do REPO LOCAL para o REPO REMOTO, e trazer alterações do REPO REMOTO para o REPO LOCAL, pois eles estão devidamente vinculados.

 

*Nota: Se preferir, pode realizar todas estas operações usando o Tortoise for GIT (instalado anteriormente), que é GUI, ao invés do GIT Bash (que é linha de comando)

 

Usando um Projeto Magic xpa integrado com o GIT

 

Ao abrir o projeto Magic xpa, vemos que a barra de título mostra que está integrado ao GIT, e qual o nome da branch atual.

 

As opções do menu “File > Version Control” também mudaram. Elas são agora um atalho para o Tortoise for GIT:

 

A ação que antes (no TFS/VSS/CVS) era chamada de “Get Project Latest Version“, agora é executada pela opção:

• GitSync > Pull

A ação que antes (no TFS/VSS/CVS) era chamada de “Check Out“, agora não existe mais. No GIT todas as alterações são sempre locais, e não existe o conceito de bloquear um arquivo para edição, no servidor/repositório remoto. Isso permite por exemplo que o DEV Juan e a DEV Marina alterem o mesmo programa “Pedidos” ao mesmo tempo, sem restrições.

A ação que antes (no TFS/VSS/CVS) era chamada de “Check In“, agora é executada pelas opções (em sequência):

• GitSync > Commit
• GitSync > Push

*Nota: Sim, existe o "check in" mesmo sem existir o "check out". TFS e GIT possuem conceitos bem diferentes e "check out" no GIT significa outra coisa (switch).

 

De forma resumida:

• Trazer alterações do REPO REMOTO para o REPO LOCAL: GitSync > Pull
• Efetivar alterações feitas no REPO LOCAL: GitSync > Commit
• Enviar alterações efetivadas no REPO LOCAL para o REPO REMOTO: GitSync > Push

*Nota: Lembre-se: os demais DEVs só tem acesso ao que for enviado ao REPO REMOTO, ou seja, depois do "push".

 

Exemplo: Ao criamos um novo programa:

 

o comando:

git status

 

mostra que existem dois arquivos do projeto que foram alterados e/ou criados:

 

Se fizermos então um GitSync > Commit:

 

Seguido de um GitSync > Push:

 

Estas alterações ficam então sincronizadas no REPO REMOTO (GitHub):

*Nota: Os demais DEVs devem fazer um GitSync > Pull para puxar estas atualizações

 

Para resumir: a sequência básica no TFS/VSS/CVS seria:

• “Get Project Lastest Version” > “Check Out” > { alterações via Studio } > “Check In”

 

Agora no GIT seria:

• “GitSync PULL” > { alterações via Studio } > “GitSync COMMIT” > “GitSync PUSH”

 

Trazendo um projeto do GitHub (REPO REMOTO) para a máquina do DEV

 

Outro cenário, é quando o DEV vai trabalhar com um projeto que ele ainda não possui localmente, mas que está lá no REPO REMOTO (GitHub).

Ele precisa então trazer este projeto para a sua máquina.

Primeiro, ele precisa ter acesso a url GIT do projeto remoto:

ex: https://github.com/desenvmagicbr/IntegracaoMagicxpaGit.git

 

Depois, no Magic xpa Studio, ele deve usar a opção: File > Version Control > Clone Repository:

 

Informar a url e a pasta de destino:

 

e confirmar o download (clonagem do REPO):

 

Pronto. Agora tem uma cópia do projeto já com o seu REPO LOCAL na sua máquina:

 

e devidamente vinculada ao seu REPO REMOTO (para sincronização):

 

Levando um projeto LOCAL da máquina do DEV para o GIT (REPO REMOTO)

 

Outro cenário, é o DEV ter um projeto localmente apenas, não integrado ao GIT, e querer levá-lo para o GitHub.

*Nota: Remova o projeto de qualquer outro controlador de versão que esteja usando (ex: TFS/VSS/CSV), se estiver usando algum, antes de prosseguir.

 

Edite o arquivo .edp do projeto (ex: IntegracaoMagicxpaGit.edp) e ajuste as duas informações abaixo:

<VCActive val="Y"/>
<VCUseGitPlugin val="Y"/>

 

Crie um repositório novo no GitHub (REPO REMOTO) para este projeto (lembrar que cada projeto necessita de um repositório) e pegue a URL GIT dele.

Crie um arquivo “.gitignore” na mesma pasta do .edp, com a lista dos conteúdos que deseja deixar de fora da sincronização (ver exemplo):

/Source/ProgramHeaders.xml
/Source/DataSourcesIndex.xml
*.opt
*.sln
*.suo
*.log
*.lock

 

Abra o GIT Bash na pasta do projeto (pelo Windows Explorer):

 

e execute estes comando para:

• Criar o REPO LOCAL:

git init
git branch -M main

• Vincular o REPO LOCAL ao REPO REMOTO:

git remote add origin https://github.com/desenvmagicbr/IntegracaoMagicxpaGit.git <-- URL deste exemplo
git push --set-upstream origin main

• Incluir o projeto no REPO LOCAL:

git add .
git commit -a -m "Subindo o projeto no GITHUB - v1"

• Sincronizar o REPO REMOTO com o REPO LOCAL:

git push

 

Pronto. Agora o projeto tem um REPO LOCAL, vinculado ao um REPO REMOTO:

 

Transferindo um projeto do VSS/TFS/CVS para o GITHUB

 

O Magic xpa Studio usa a configuração /[MAGIC_ENV]SourceControlPlugin para saber com qual sistema de controle de versões ele deve interagir:

• /[MAGIC_ENV]SourceControlPlugin = S --> TFS/VSS/CVS

• /[MAGIC_ENV]SourceControlPlugin = G --> GIT

 

No cenário em que o DEV já tem o projeto no TFS/CVS/VSS e deseja mudar, passando para o GIT , deve proceder assim:

• Ajuste o Studio para a configuração [MAGIC_ENV]SourceControlPlugin=S e abra o projeto
• Remova-o do controle de versão atual:

 

• Ajuste o Studio novamente para a configuração [MAGIC_ENV]SourceControlPlugin=G
• Repita os passos acima, da seção: Levando um projeto LOCAL da máquina do DEV para o GIT (REPO REMOTO)

 

Histórico de Mudanças

 

Quando acessamos o menu Version Control > Show Log:

 

Podemos ver o históricos das ações (que ocorreram via git commit) no REPO LOCAL:

Selecionando um dos arquivos alterados nesse commit, com o botão direito do mouse temos acesso ao menu de “Compare“:

 

Na ação de comparação, é executado nesse momento o Magic Compare, para exibir as diferenças (antes x depois):

 

Resolvendo Conflitos com o COMPARE & MERGE

 

Uma mudança importante ref. ao conceito de REPO LOCAL distribuído (do GIT) comparado a um REPO CENTRAL (do VSS/TFS/CVS), é que dois ou mais DEVs Magic xpa podem estar alterando o mesmo objeto (tabela, modelo, menu, programa, direito, etc…) ao mesmo tempo, sem precisar comunicar aos demais.

Isso permite que (por exemplo) o DEV Juan (que usa /[MAGIC_ENV]VersionControlID=1) e a DEV Marina (que usa /[MAGIC_ENV]VersionControlID=2) alterem o mesmo programa “Pedidos“, ao mesmo tempo (sem que o outro saiba).

O motivo é que cada um tem o seu REPO LOCAL do projeto de forma independente, e toda mudança ocorre sempre no REPO LOCAL, além de não existir mais o processo de “Check Out” no REPO REMOTO (bloqueio para alterações).

Assim, se o DEV Juan levar suas alterações referentes ao programa “Pedidos” para o REPO REMOTO (git commit + git push), posteriormente quando a DEV Marina tentar a mesma coisa, ela não vai conseguir. O GIT acusará um conflito de versões (o REMOTO tem novidades que o LOCAL não tem).

A DEV Marina (que é quem está tentando por último) precisa então fazer um git pull para sincronizar novamente o seu REPO LOCAL com o REPO REMOTO.

É nessa hora que ocorre o conflito.

Pois há mudanças no programa “Pedidos” local que ainda não foram sincronizadas no GitHub, e está chegando uma “nova versão” deste programa (remota) para sobrescrevê-lo.

Nesse momento precisamos (obrigatoriamente) usar o Compare & MERGE (C&M) do Magic xpa

*Nota: O C&M é vendido e licenciado separadamente

 

Durante o git pull, o C&M analisa as mudanças e diferenças do programa Pedidos no REPO LOCAL da DEV Marina, em relação a versão atualizada deste programa no REPO REMOTO (GitHub), e permite a DEV Marina “mesclar” as versões, a fim de não perder totalmente as mudanças que ela já fez localmente.

 

São basicamente três opções oferecidas ao DEV na solução do conflito:

• Acatar a versão completa (e nova) do REPO REMOTO, e descartar suas mudanças locais
• Manter a versão anterior, da última vez que este programa (objeto) esteve atualizado em relação ao REPO REMOTO
• Combinar (MERGE) as duas versões, e gerar uma terceira versão (final)

 

Se Juan e Marina (e os demais DEVs) optarem por não usar o C&M, eles precisam combinar entre si de nunca alterarem o mesmo objeto ao mesmo tempo, sob pena deles perderem suas mudanças caso o outro seja mais rápido e suba estas mudanças no GitHub.

Este é um processo manual e falho, e muito trabalhoso de implantar cfe. for crescendo a equipe de DEVs.

Mas claro, que no modelo de “euquipe” (um único DEV por projeto xpa), o C&M não é necessário.

 

Para usar o C&M, baixe-o e instale-o na sua máquina (DEV) cfe. explicado mais acima.

Localize e guarde o caminho onde foram instalados os programas “MagicCompare.exe” e “Merge.exe“:

 

Usando o Tortoise for GIT, configure o Diff Viewer:

 

e o Merge Tool:

 

para estes dois programas do pacote C&M.

 

Agora, observe esta situação:

 

Juan e Marina tem esta versão do mesmo programa:

 

Juan fez algumas alterações neste programa, na sua cópia do projeto, enquanto Marina também fez alterações (ao mesmo tempo) no mesmo programa, na sua cópia do projeto.

Juan finaliza as mudanças e atualiza o GitHub (com git commit + git push):

 

Marina também finaliza as mudanças e tenta atualizar o GitHub (com git commit + git push):

 

O git commit de Marina não tem problema, mas na hora do git push, ocorre a rejeição:

 

por conta do conflito explicado anteriormente.

Marina então precisa (tem que) fazer um git pull, para buscar estas atualizações e sincronizar o seu REPO LOCAL com o REPO REMOTO.

E nessa hora, é exibida causa do conflito:

 

*Nota: estas interfaces todas não são do Magic xpa, mas sim, do Tortoise for GIT.

 

Este arquivo XML é o arquivo com o código-fonte do programa que está com problemas de sincronia (LOCAL x REMOTO).

Nesse momento, o GIT alterou o conteúdo do arquivo com algumas marcações especiais (dos pontos de divergência):

 

Isso deixa este arquivo XML tecnicamente inválido.

Por isso é muito importante o uso C&M nesse momento, do contrário o resultado será um objeto (ex: programa) corrompido no Magic xpa:

 

Agora, usando o botão direito do mouse em cada arquivo (objeto) que está em conflito, deve-se escolher a opção “Edit Conflicts”:

 

Nesta hora, o C&M é executado:

 

São apresentados 4 painéis com detalhes das versões do objeto em conflito:

• BASE: É a versão comum, ou seja, a última versão em que este objeto (ex: programa) estava corretamente sincronizado entre o REPO LOCAL e o REPO REMOTO
• REMOTE: É a versão atual, lá no REPO REMOTO
• LOCAL: É a versão atual, aqui no REPO LOCAL
• MERGED OUTPUT: É como o objeto (ex: programa) vai ficar, após a resolução manual destes conflitos

 

Veja outro exemplo:

 

A resolução dos conflitos ocorre no quadro MERGED OUTPUT.

Existem duas setas disponíveis em cada linha:

 

A seta AZUL é para acatar a versão desta linha, vinda do “BASE“.

A seta VERDE, é para acatar a versão desta linha, vinda do “REMOTE“.

*Nota: Importante destacar que o MERGE ocorre sempre entre as versões "BASE" e "REMOTE" (e não com a "LOCAL")

 

No menu superior do C&M existem as opções:

• Take Source Branch: Acatar toda a versão “BASE” como sendo a final
• Take Target Branch: Acatar toda a versão “REMOTE” como sendo a final
• Merge: Finaliza a solução dos conflitos e gera a versão (nova) atualizada, para o REPO LOCAL

 

*Nota: Se o C&M não conseguir fazer o MERGE (por considerar as mudanças muito complexas), serão oferecidas estas duas opções: Take Source Branch e Take Target Branch

Uma vez que os conflitos foram resolvidos e clica-se “Merge“, o C&M é finalizado, e retorna para esta tela:

 

Neste momento, deve-se selecionar o mesmo objeto (programa) e escolher a opção “Resolved”:

 

Para informar ao GIT que este problema já foi solucionado.

A DEV Marina pode então repetir o seu git commit + git push, se desejar.

A sua versão local do programa foi atualizada com o resultado final do “Merge“.

 

Dica💡: Se a/o DEV (ex: Marina) quiser fazer a sua nova versão prevalecer, ela precisa salvar (backup) seu programa [usando o EXPORT do xpa], resolver os conflitos do git pull, restaurar este backup [usando o IMPORT do xpa], e fazer então um  novo git commit + git push.

 

E pronto. Resumimos assim o processo de integração Magic xpa com GIT.

 

Fique ligado no Blog MagicBR, para mais dicas.

 

Para receber os artigos do Blog Magic Brasil em primeira mão no seu email, registre-se aqui