Capítulo 3. A Área de Trabalho

Esta tradução pode estar desatualizada. Para ajudar com as traduções, acesse a ferramenta de traduções do FreeBSD.

A área de trabalho é uma cópia da árvore de documentação do repositório do FreeBSD baixada no computador local. As alterações são feitas na cópia de trabalho local, testadas e enviadas como patches para serem submetidas no repositório principal.

Uma cópia completa da árvore de documentação pode ocupar 700 megabytes de espaço em disco. Tenha um gigabyte de espaço total para ter sobra para arquivos temporários e versões de teste dos diversos formatos de saída.

O Git é utilizado para gerenciar os arquivos de documentação do FreeBSD. Ele é obtido pela instalação do pacote devel/git, e também por uma versão mais leve chamado git-lite:

# pkg install git-lite

3.1. Documentação e Páginas de Manual

A documentação do FreeBSD não é formada apenas por livros e artigos. Páginas de manual para todos os comandos e arquivos de configuração também fazem parte da documentação e fazem parte do território do FDP. Dois repositórios estão envolvidos: doc para os livros e artigos, e src para o sistema operacional e páginas de manual. Para editar páginas de manual, o repositório src deve ser obtido separadamente.

Repositórios podem conter várias versões de documentação e código-fonte. Novas modificações quase sempre são feitas apenas para a versão mais recente, chamada main.

3.2. Escolhendo um Diretório

A documentação do FreeBSD é tradicionalmente armazenada em /usr/doc/, e o código fonte do sistema com páginas de manual em /usr/src/. Essas árvores são realocáveis e os usuários podem armazenar as cópias de trabalho em outros locais para evitar interferir nas informações existentes nos diretórios principais. Os exemplos a seguir utilizam ~/doc e ~/src, ambos subdiretórios do diretório pessoal do usuário.

3.3. Baixando uma Cópia

O processo de download de um repositório é chamado de clone e é feito com um git clone. Este exemplo faz a clonagem de uma cópia da versão mais recente (main) do repositório de documentação principal:

% git clone https://git.FreeBSD.org/doc.git ~/doc

O checkout do código-fonte para trabalhar nas páginas de manual é muito semelhante:

% git clone https://git.FreeBSD.org/src.git ~/src

3.4. Atualizando

Os documentos e arquivos no repositório do FreeBSD mudam diariamente. As pessoas modificam arquivos e submetem alterações com frequência. Mesmo após um checkout inicial, já haverá alterações entre a cópia de trabalho local e o repositório principal do FreeBSD. Para atualizar a versão local com as mudanças que foram feitas no repositório principal, execute git pull no diretório que contém a cópia de trabalho local:

% cd ~/doc
% git pull --ff-only

Adquira o hábito protetor de usar git pull antes de editar arquivos de documentos. Alguém pode ter editado aquele arquivo recentemente, e a cópia de trabalho local não incluirá as últimas mudanças até que tenha sido atualizada. Editar a versão mais recente de um arquivo é muito mais fácil do que tentar combinar um arquivo local editado mais antigo com a versão mais recente do repositório.

3.5. Revertendo Alterações

De vez em quando acontece que algumas mudanças não eram necessárias, ou o escritor só quer começar novamente. Arquivos podem ser "resetados" para sua forma anterior com git restore. Por exemplo, para apagar as alterações feitas no _index.adoc e redefini-las para o formato sem modificação:

% git restore _index.adoc

3.6. Criando um Diff

Após finalizar as alterações em um arquivo ou grupo de arquivos, as diferenças entre a cópia de trabalho local e a versão no repositório do FreeBSD devem ser coletadas em um único arquivo para ser submetido. Estes arquivos diff são produzidos redirecionando a saída de git diff para um arquivo:

% cd ~/doc
% git diff > doc-fix-spelling.diff

Dê ao arquivo um nome significativo que identifique o conteúdo. O exemplo acima é para correção ortográfica em toda a árvore de documentação.

Se o arquivo diff for enviado com a interface web "Submit a FreeBSD problem report", adicione uma extensão .txt para que o formulário web identifique que o conteúdo do arquivo é texto plano.

Tenha cuidado: git diff inclui todas as alterações feitas no diretório atual e em quaisquer subdiretórios. Se houver arquivos na cópia de trabalho com edições que ainda não estão prontas para serem enviadas, forneça uma lista apenas dos arquivos a serem incluídos:

% cd ~/doc
% git diff disks/_index.adoc printers/_index.adoc > disks-printers.diff

3.7. Referências Git

Estes exemplos demonstram um uso muito básico do Git. Mais detalhes estão disponíveis no Git Book e na Documentação do Git.


Última alteração em: 21 de maio de 2023 por Danilo G. Baio