Como adicionar documentação ao pacote Git no NixOS?

Então, na maioria das vezes, o Nix coloca os arquivos exatamente como em uma distribuição FHS normal, exceto que ele prefixa o caminho com /nix/store/somehash-somename/(com iguais $outno momento da construção) e remove alguns caminhos. /usr/Por exemplo, como nas distribuições FHS /usr/localcontêm basicamente a mesma estrutura dos / programas instalados pelos usuários (o que não é necessário no nix), o nix removerá os prefixos /usre . /usr/localIsso é bastante prático, pois dessa forma o nix pode simplesmente definir $PREFIX=/nix/store/somehash-somename/(que geralmente é definido por padrão como /usr/local) e executar como ele a maioria dos scripts auto-tools/cmake/make existentes.

Em particular, como nas distribuições normais do FHS as páginas de manual estão localizadas em /usr/share/man, no nix precisamos apenas instalar as páginas de manual em $out/share/man.

Agora, para resolver seu problema específico, o mais difícil é realmente entender como o git está encontrando a documentação de seus comandos. Já que você mencionou o git diffcomando, vamos inspecionar a pasta git para descobrir onde ela armazena os arquivos de documentação:

$ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.gitFull'
/nix/store/hvl0fxxkva3ql9ksiy8p8pl3cxli24l8-git-with-svn-2.39.0
$ cd /nix/store/hvl0fxxkva3ql9ksiy8p8pl3cxli24l8-git-with-svn-2.39.0
# fd is a really cool tool to quickly search files based on their name
$ fd diff
…
share/man/man1/git-diff.1.gz
…

Bingo, parece que a documentação é um manarquivo simples. Na verdade, se executarmos:

$ git help mytest
No manual entry for gitmytest

parece que o git é executado diretamente man gitmytest(não sei por que não há mais traço envolvido aqui…), e isso parece funcionar mesmo que mytestnão seja um comando git existente. Então, só precisamos criar uma entrada man para gitmytest!

Para isso, vamos criar este template em um novo arquivo git-mytest(obtido apenas pesquisando no Google como criar uma página de manual):

.\" Manpage for git mytest.
.TH man 1 "06 May 2010" "1.0" "git mytest man page"
.SH NAME
git mytest \- test to document random git commands
.SH SYNOPSIS
git mytest [USERNAME]
.SH DESCRIPTION
git mytest is a non-existing command that I use to do some tests.
.SH OPTIONS
Since it does not even exists, there is little chance it has options.
.SH SEE ALSO
useradd(8), passwd(5), nuseradd.debian(8) 
.SH BUGS
No known bugs.
.SH AUTHOR
Tobias Bora ([email protected])

Então, só precisamos criar um pacote básico para instalar isso. Observe que não há necessidade de override gitFull, podemos apenas criar um novo pacote para instalá-lo em um pacote separado. Em meus testes, usarei um default.nixarquivo contendo:

{ pkgs ? import <nixpkgs> {} }:
pkgs.stdenv.mkDerivation {
  name = "git-mytest";
  src = ./.;
  buildPhase = "";
  installPhase = ''
    mkdir -p $out/share/man/man1
    cp $src/git-mytest $out/share/man/man1/gitmytest.1
  '';
}

Podemos construí-lo e verificar se o arquivo foi produzido corretamente:

$ nix-build
$ ls ./result/share/man/man1
gitmytest.1.gz

Legal, nix até comprimiu para nós. Para verificar se o conteúdo é bom, você pode executar zcat ./result/share/man/man1/gitmytest.1.gze ele imprimirá o arquivo descompactado.

Agora é hora de tentar. Uma solução é instalá-lo diretamente em todo o sistema, inserindo a derivação acima em seu configuration.nixou em outro lugar. Mas para fins de teste, eu queria evitar instalá-lo globalmente, então acabei de criar um shell.nixque carrega o pacote que acabamos de criar:

{ pkgs ? import <nixpkgs> {} }:
with pkgs;
let mantest = import ./default.nix { inherit pkgs; }; in
pkgs.mkShell {
  packages = [ mantest ];
  buildInputs = [ ];
  shellHook = ''
    echo "Exporting manpage path"
    export MANPATH=${mantest}/share/man:$MANPATH
  '';
}

Você pode ver que eu adicionei um shellHook: esta linha é realmente necessária apenas para este teste, a fim de especificar manonde ele deve procurar as páginas de manual. Mas depois de instalar o programa, isso não será mais necessário.

Depois, basta carregar o shell e testá-lo:

$ nix-shell
$ git help mytest
# you should get the man page printed!

Funciona! Aproveitar ;-)

EDITAR Ok, parece que as instruções acima não funcionam se um alias for criado; nesse caso, a mensagem é sempre a mesma myalias is aliased to XXX. Isso vem desta linha do código e parece impossível de evitar diretamente. No entanto, em vez de criar um alias, você pode simplesmente criar um novo plugin git (e se precisar documentá-lo, é provável que faça sentido criar um), ou seja, um arquivo binário chamado (ao executar, o git será git-mytestexecutado git mytestautomaticamente git-mytest). git-mytestpode ser um script bash simples chamando o git diretamente. Isso pode ser feito da seguinte maneira (observe que desta vez você precisa escrever os hifens na página de manual, parece que ele atribui nomes de páginas de manual diferentes dependendo do tipo de comando):

{ pkgs ? import <nixpkgs> {} }:
pkgs.stdenv.mkDerivation {
  name = "git-mytest";
  src = ./.;
  buildPhase = "";
  installPhase = ''
    mkdir -p $out/share/man/man1
    mkdir -p $out/bin
    # "git mytest" will run "git-mytest", so we just need to create a binary called "git-mytest"
    # (nix will automatically patch /bin/bash, so it's fine to use here, the "$@$ in the bash forwards the argument to the command)
    echo '#!/bin/bash' > $out/bin/git-mytest
    echo 'git log --all --graph "$@"' >> $out/bin/git-mytest
    chmod +x $out/bin/git-mytest
    # Installs the documentation for the command
    # this time, if the command exists, you do need a "-"
    cp $src/git-mytest $out/share/man/man1/git-mytest.1
  '';
}

apenas substitua o default.nixarquivo acima por este e execute novamente nix-shell. Então, você deve digitar bem:

$ git mytest
# runs git log --all --graph

$ git help mytest
# prints the man page

$ git mytest -h
# Prints the help of "git log" since for now we forward the arguments.
# If you want "git mytest -h" to print a different message, just search for "-h" in the arguments in the bash script and run for instance "man git-mytest" yourself.