☰

如何在 NixOS 中向 Git 包添加文档？

tag-icon • tag-icon nixos nix
如何在 NixOS 中向 Git 包添加文档？

git help some-alias打印别名配置值，例如：

$ git help aliases
'aliases' is aliased to '!git config --get-regexp '^alias\.' | cut --delimiter=. --fields 2-'

我想以与其他别名相同的方式提供此别名和其他别名的详细帮助git help diff。到目前为止我已经这:

{
  config.programs.git.package = pkgs.gitFull.overrideAttrs (
    old: {
      postInstall =
        old.postInstall
        + ''
          cp ${./includes/git-aliases/docs}/* $doc/share/doc/git/
        '';
    }
  );
}

它成功地复制了一些文本文件/nix/store/[git package]-doc/share/doc/git/，但是这些文件在运行时并没有显示出来，例如git help aliases。

我还需要做什么才能将文档链接到help子命令？更新一些文件注册表？.html即使我只想要 CLI 文档，也要添加文件吗？还有别的事吗？

答案1

因此，大多数时候，Nix 放置文件的方式与正常 FHS 发行版中的放置方式完全相同，只是它在路径前加上前缀/nix/store/somehash-somename/（在构建时使用 equals $out），并且删除了一些路径。例如，在 FHS 发行版中，/usr/和/usr/local包含与以下基本相同的结构：/ 对于用户安装的程序（nix 中不需要），nix 将删除/usr和/usr/local前缀。这是非常实用的，因为这样 nix 可以简单地设置$PREFIX=/nix/store/somehash-somename/（通常默认设置为/usr/local）并按原样运行大多数现有的自动工具/cmake/make 脚本。

特别是，由于在正常的 FHS 发行版中手册页位于 中/usr/share/man，因此在 nix 中我们只需将手册页安装在 中$out/share/man。

现在，为了解决您的具体问题，最困难的部分实际上是理解 git 如何查找其命令的文档。既然您提到了该git diff命令，让我们检查 git 文件夹以找出它存储文档文件的位置：

$ 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
…

宾果，看起来文档是一个简单的man文件。实际上，如果我们运行：

$ git help mytest
No manual entry for gitmytest

看起来 git 直接运行man gitmytest（不知道为什么这里不再涉及破折号......），即使mytest不是现有的 git 命令，这似乎也可以工作。所以我们只需要创建一个 man 条目gitmytest！

为此，让我们在一个新文件中创建此模板git-mytest（通过谷歌搜索如何创建手册页即可获得）：

.\" 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])

然后，我们只需要创建一个基本包来安装它。请注意，无需覆盖gitFull，我们只需创建一个新包将其安装在单独的包中即可。在我的测试中，我将使用一个default.nix包含以下内容的文件：

{ 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
  '';
}

我们可以构建它并检查文件是否已正确生成：

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

很酷，nix 甚至为我们压缩了它。要仔细检查内容是否正确，您可以运行它zcat ./result/share/man/man1/gitmytest.1.gz，它将打印未压缩的文件。

现在，是时候尝试一下了。一种解决方案是直接在系统范围内安装它，方法是将上述推导插入到您的configuration.nix或其他位置。但出于测试目的，我想避免全局安装它，所以我只是创建了一个shell.nix加载我们刚刚创建的包的程序：

{ 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
  '';
}

您可以看到我添加了一条shellHook：实际上仅此测试需要此行，以便指定man应在何处查找手册页。但一旦您实际安装了该程序，就不再需要它了。

然后，加载 shell 并进行测试：

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

有用！享受 ;-）

编辑 好吧，如果创建了别名，上面的说明似乎不起作用，在这种情况下，消息总是相同的myalias is aliased to XXX。这来自这条线在代码中，似乎无法直接避免。然而，您可以简单地创建一个新的 git 插件（如果您需要记录它，那么创建一个别名可能是有意义的），而不是创建别名，即一个名为git-mytest（运行时git mytest，git 将自动运行git-mytest）。git-mytest可以是直接调用 git 的简单 bash 脚本。这可以按如下方式完成（请注意，这次您需要写连字符在手册页中，它似乎根据命令的类型赋予不同的手册页名称）：

{ 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
  '';
}

只需default.nix用此替换上面的文件，然后再次运行即可nix-shell。然后，你应该可以输入：

$ 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.

相关内容