Como usar o gource

Gource

O gource é um software que monta uma animação grafica em formato de árvore do seu repositório Git, Mercurial, Bazaar e SVN, a partir dos commits. Exemplo aqui.

A cada bimetre é necessário postar um vídeo produzido pelo gource no Youtube para cada equipe, segundo a bíblia https://dicas.ivanfm.com/aulas/pds.html, desde o início do ano. O vídeo deve conter esses tópicos:

• Alterar os userid do repositório por nomes dos participantes
• colocar uma imagem distinta e especifica para cada usuário
• utilizar opção –key
• utilizar as opções de caption para registrar as principais mudanças feitas no repositório
• os vídeos devem ter no máximo 1 minuto para cada bimestre

Esse post é para facilitar a usabilidade na hora de gerar o vídeo. Também para que não fique faltando nada (para não perder notinha), e que não seja somente mais um tutorial com scripts não explicados.

Mão na massa

O mínimo necessário para gerar o vídeo do gource.

Instalação

No Windows baixe esse arquivo. É necessário que seu sistema seja 64bits, caso não saiba como veja isso, veja esse link.

No Ubuntu basta executar $ sudo apt-get install gource.

Outras distros linux sigam esse tutorial.

Para gerar o vídeo é necessário o ffmpeg. Windows, Ubuntu $ sudo apt-get install ffmpeg

Rodando

Antes de rodar o comando gource no termial ou cmd, certifique que esteja com o SVN instalado. Clone o repositório dentro de uma pasta e abra o cmd ou terminal no local. No Windows pressione SHIFT+Botão Direito e vá até a opçao "Abrir janela de comando aqui", como mostra abaixo:



No linux somente pressione o botão direito e abra o terminal/shell aqui.

Digite gource, se aparecer o vídeo, parabéns! Gource instalado com sucesso. Pode apertar ESC para sair, porque ainda faltam os requisitos.

Dando nomes aos avatares

Primeiro precisamos criar um log customizado. Para isso digite
gource --output-custom-log <AQUI VAI O NOME DO LOG CUSTOMIZADO>

Depois entre no arquivo e altere os respectivos sp+prontuário pelo nome dos integrantes. Exemplo:

1551558531|sp1550543|A|/A2019-PDS413/AnEisiata/Videos
1552268140|sp1651153|A|/A2019-PDS413/AnEisiata/Documentos/LaTeX/proposta-inicial
1552268140|sp1651153|A|/A2019-PDS413/AnEisiata/Documentos/LaTeX/proposta-inicial/00-info.tex

Para:

1551558531|Enzo|A|/A2019-PDS413/AnEisiata/Videos
1552268140|Glayson|A|/A2019-PDS413/AnEisiata/Documentos/LaTeX/proposta-inicial

Dica: Utilizem o replace all dos editores de texto, facilitarão suas vidas.
Caso esteja usando o linux sed é um ótimo comando. Exemplo:
$ sed -i "s|sp1651153|Glayson|g" <AQUI VAI O NOME DO LOG CUSTOMIZADO>

Colocando rostos aos avatares

Insira uma pasta ao seu repositório, nomeie como quiser, depois disso é preciso que coloque dentro dessa pasta as imagens de cada usuário, com o respectivo nome. Exemplo:
Pasta: images
Nome: Glayson.png
Nome: Enzo.jpg
Nome: Kaynnan.jpeg

Nota: o nome da imagem deve ser o mesmo nome que foi inserido anteriormente. Não testei outros formatos de imagens, mas garanto que png e jpeg funcionam.

Explicando o vídeo

Crie um arquivo de caption, vá no arquivo de log customizado procure os commits mais importantes, copie os primeiros números, coloque um pipe ( | ), e descreva aquela ação. Exemplo.
custom.log
1551558531|Enzo|A|/A2019-PDS413/AnEisiata/Videos
1552268140|Glayson|A|/A2019-PDS413/AnEisiata/Documentos/LaTeX/proposta-inicial

caption.txt
1551558531|Videos
1552268140|Proposta Inicial

Faça isso para os commits que julgar serem os mais importantes.
É possível definir o tempo para cada caption com a flag --caption-duration SECONDS (1, 2, 0.5, 0.25).

Tempo ideal

O gource não possui um atributo para definir o tamanho do vídeo, mas sim o período que ele vai aparecer por commits, então a ideia é ficar testando o ideal para cada repositório. A flag que altera o tempo por commits é --max-file-lag SECONDS (1, 2, 0.5, 0.25).

Gerando o vídeo

Se tudo ocorrer bem é só digitar

gource <LOG CUSTOMIZADO> --key --user-image-dir <PASTA COM AS IMAGENS> --caption-file <ARQUIVO DE CAPTION> --caption-duration <SECONDS> --max-file-lag <SECONDS> -o <NOME DO ARQUIVO GOURCE PPM>. 

Depois digite

ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i <ARQUIVO GOURCE PPM> -vcodec libx254 -preset medium -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 <NOME DO ARQUIVO MP4>

Exemplo:
gource custom.log --key --user-image-dir membros --caption-file caption --caption-duration 5 --max-file-flag 5 -o gource.ppm


ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i gource.ppm -vcodec libx254 -preset medium -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 gource.mp4

Finalizado

Antes de colocar nome é importante lembrar que o funcionamento do gource é a partir de log, basicamente, ele lê algum log e gera o vídeo, então para que ele adicione nomes e não prontuários, é necessário alterar o log do Subversion.
Obviamente que um Subversion não vai deixar qualquer um fazer isso, seria o oposto de um controlador de versão, tendo essa limitação, é necessário gerar um log customizado. O log customizado oficial do gource é no formato CSV separado por pipes ( | ). O nome do usuário fica na segunda coluna da linha, sendo a primeira o tempo em milissegundos do commit, a terceira o tipo de commit (A - adicionado, M - Modificado, D - Deletado) e o quarto o nome arquivo ou diretório.
O caption contém o mesmo funcionamento, com CSV, agora com duas colunas, primeiro o tempo em millisegundos e segundo a descrição daquele momento no vídeo.
Ao utilizar o argumento --user-image-dir passando o diretorio, o gource pega o nome do usuário e substitui a imagem padrão.

Para maiores detalhes clique aqui e utilize o comando gource --help