Darcs 2.18.5 配置参数详解

Darcs 2.18.5 配置详解：用户级 ~/.darcs/defaults 与仓库级 _darcs/prefs/*（defaults/boring/binaries/motd/prefs/defaultrepo/repos）的优先级与实测，14 个环境变量（颜色、TMPDIR、EDITOR、SSH、连接超时）、远程 URL 与 ~/.ssh/config、全局缓存，含 8 项实测回显与排障实录。

DarcsDarcs版本控制Haskell2026/10/27

Darcs 2.18.5 配置参数详解

目标：把 Darcs 的四层配置讲透——用户级 ~/.darcs/、仓库级 _darcs/prefs/、环境变量、命令行参数，并给出 8 项在本机实测生效的配置及其原样回显。所有命令在 Ubuntu 22.04.5 + Darcs 2.18.5 上执行，测试仓库 /root/lab/repoA，作者 admin <admin@example.com>。

一、配置分层与优先级

层级位置作用范围典型内容
用户级~/.darcs/defaults、~/.darcs/author当前用户所有仓库默认命令选项、作者
仓库级_darcs/prefs/defaults、prefs、boring、binaries、motd、defaultrepo、repos、sources、author单个仓库仓库默认选项、忽略/二进制规则、公告、默认远端
环境变量Shell 环境当前进程编辑器、分页器、颜色、临时目录、SSH 客户端
命令行darcs <cmd> ...单次调用最高优先级，覆盖以上全部

实测优先级：仓库级 defaults > 用户级 defaults。将 ~/.darcs/defaults 写 log --last 2、_darcs/prefs/defaults 写 log --last 1，执行 darcs log | grep -c '^patch ' 输出 1，证明仓库级覆盖用户级。命令行再传 --last 5 则以 5 为准。

二、用户级 ~/.darcs/

2.1 defaults 文件格式

每行一条「命令名 + 选项」，# 开头为注释。命令名用长名（record、log、push），不要带 darcs 前缀。

mkdir -p ~/.darcs
cat >> ~/.darcs/defaults <<'EOF'
record --author "ops <ops@example.com>"
log --last 1
EOF

实测记录一个补丁：

darcs record -a -m 'defaults demo'
darcs log

Finished recording patch 'defaults demo'
patch 575ec37f203fc97ee6e06ea1a28195af87ebcd83
Author: "ops <ops@example.com>"
Date:   Tue Oct 27 12:32:47 UTC 2026
  * defaults demo

两个结论：

  1. record --author 生效，作者被改成 ops；
  2. 双引号被原样写入作者字段，日志显示 Author: "ops <ops@example.com>"。正确写法是不加引号：record --author ops <ops@example.com>（尖括号与空格在 defaults 文件中按行解析，不需要 shell 引号）。

log --last 1 同时生效——darcs log 只输出最近 1 条。测试后记得删除该文件，避免影响后续排查。

2.2 author 文件

~/.darcs/author 每行一个作者串；record 未指定 --author 时按 --author → _darcs/prefs/author → ~/.darcs/author → $DARCS_EMAIL/$EMAIL 顺序查找，都没有才交互询问。实测内容：

admin <admin@example.com>

三、仓库级 _darcs/prefs/

实测目录内容（初始化后按需生成）：

binaries
boring
defaultrepo
repos

3.1 _darcs/prefs/defaults

只对本仓库生效，格式与用户级一致。实测写入 whatsnew --summary 后：

echo 'whatsnew --summary' > _darcs/prefs/defaults
darcs whatsnew

M ./hello.txt +1

原本逐行 hunk 的输出变成单行摘要。该文件适合放「本仓库特有」的默认行为（例如统一 --test、--ignore-times），不要放个人作者信息。

3.2 _darcs/prefs/boring（忽略规则）

每行一个 POSIX 扩展正则（不是 glob）。测试时先踩了坑：

echo '*.o' > _darcs/prefs/boring
touch foo.o
darcs whatsnew

Warning: Ignored invalid boring regex: *.o
No changes!

*.o 在正则里是非法表达式（* 前缺原子），Darcs 打印警告并忽略该行。正确写法：

printf '.*\.o$\n' > _darcs/prefs/boring
touch foo.o
darcs whatsnew

No changes!

foo.o 被正确忽略。规则按仓库生效，等价于 Git 的 .gitignore，但语法是正则，写 glob 会静默失效（只在首次加载时告警）。

3.3 _darcs/prefs/binaries（二进制规则）

同样使用 POSIX 正则。实测把 .*\.png$ 加入后，修改图片文件不再尝试逐行 diff：

printf '.*\.png$\n' > _darcs/prefs/binaries
printf '\x89PNG\r\n\x1a\n2222' > logo.png
darcs whatsnew

binary ./logo.png

若不配置该文件，Darcs 会把 PNG 当文本做行级差异，既慢又可能产生巨大 hunk。二进制文件应当在 add 之前就配好规则。

3.4 _darcs/prefs/motd（仓库公告）

写入任意文本，在他人 clone/pull 该仓库时显示（本仓库内执行普通命令不显示）：

echo '== repoA maintenance window ==' > _darcs/prefs/motd
cd /root/lab && darcs clone repoA repoM

== repoA maintenance window ==
**********************
Copying patches, to get lazy repository hit ctrl-C...
Finished cloning.

适合放维护窗口、迁移通知、只读提示。

3.5 _darcs/prefs/prefs（仓库偏好键值）

由 darcs setpref 维护，格式为 键 值。实测设置 test：

darcs setpref test 'echo TEST-RAN'
cat _darcs/prefs/prefs

test echo TEST-RAN

test 是提交前测试脚本，只有加 --test（或在 defaults 里配 record --test）才会执行。实测把脚本改成 exit 1 后：

darcs record -a --test -m 'test pref demo'

Running test...
Test failed!
ExitFailure 1
Failed to record patch 'test pref demo'

补丁被正确拒绝入库。清空用 darcs setpref test ''。

3.6 _darcs/prefs/defaultrepo 与 repos

defaultrepo 保存默认远端，由 --set-default 写入。实测指向 SSH 仓库：

darcs push -a --set-default ssh://darcs-lab//root/lab/repoM
cat _darcs/prefs/defaultrepo
darcs push -a

ssh://darcs-lab//root/lab/repoM
Pushing to "ssh://darcs-lab//root/lab/repoM"...
No recorded local patches to push!

repos 记录本仓库交互过的远端清单，实测内容：

/root/lab/repoB
ssh://darcs-lab//root/lab/repoM
/root/lab/repoD

该文件由 Darcs 自动维护，不建议手改；sources 在部分传输路径下才会生成，本次测试未出现，属正常现象。

3.7 _darcs/prefs/author 与 tmpdir

  • author：仓库级作者，优先级高于 ~/.darcs/author；
  • tmpdir：仓库级临时目录，优先级低于 $DARCS_TMPDIR、高于系统 /tmp。

四、环境变量

darcs help environment 是权威清单。常用项与实测结论：

变量作用实测/说明
DARCS_EDITOR / VISUAL / EDITOR编辑补丁描述依次回退；都未设时用 nano，再退 vi/emacs
DARCS_PAGER / PAGER分页器设为空字符串可禁用分页（本文所有回显均 DARCS_PAGER=）
DARCS_ALWAYS_COLOR强制 ANSI 颜色实测 DARCS_ALWAYS_COLOR=1 输出 ^[[36mpatch ...^[[00m
DARCS_DONT_COLOR关闭颜色实测输出无任何转义序列
DARCS_ALTERNATIVE_COLOR用加粗/反显替代彩色适配单色终端
DARCS_DONT_ESCAPE_ANYTHING关闭控制字符转义管道给自定义分页器时使用，注意安全风险
DARCS_TMPDIR / TMPDIR临时目录实测 DARCS_TMPDIR=/root/dtmp，darcs diff 生成 darcs-diff-2d0bbc84248415c9
DARCS_KEEP_TMPDIR保留临时目录与上者配合，便于排查 test 脚本失败
DARCS_EMAIL / EMAIL作者串回退优先级低于 author 文件
DARCS_SSH替换 ssh 客户端见第五节实测异常
DARCS_SCP / DARCS_SFTP替换 scp/sftpDARCS_SCP=rsync 可加速 clone
SSH_PORT非 22 端口推荐改用 ~/.ssh/config 的 Port
DARCS_CONNECTION_TIMEOUT连接超时秒数默认 30，仅 curl 传输生效
DARCS_SLOPPY_LOCKS宽松锁NFS 等文件系统报 atomic_create 时尝试

颜色实测：

env -u DARCS_DONT_COLOR DARCS_ALWAYS_COLOR=1 TERM=xterm script -qec 'darcs log --last 1' /dev/null | cat -v

^[[36mpatch ^[[00m^[[36m641189546e693b0a69dd4efddab0c131deadb333^[[00m^[[00m
Author: admin <admin@example.com>^[[00m

临时目录实测：

mkdir -p /root/dtmp
DARCS_TMPDIR=/root/dtmp DARCS_KEEP_TMPDIR=1 darcs diff --last 1 >/dev/null
ls /root/dtmp

darcs-diff-2d0bbc84248415c9

五、远程仓库 URL 与 SSH

5.1 URL 写法

写法示例说明
本地路径/root/lab/repoA、../repoB最快，用于本机/挂载盘
SSH 简写darcs-lab:/root/lab/repoA走 ~/.ssh/config 的 Host 别名
SSH URLssh://darcs-lab//root/lab/repoA双斜杠，第二个才是绝对路径开头
HTTP(S)https://host/repo只读拉取为主

5.2 SSH 配置与实测

~/.ssh/config：

Host darcs-lab
    HostName 127.0.0.1
    User root
    IdentityFile /root/.ssh/id_ed25519
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

两种写法均克隆成功：

darcs clone darcs-lab:/root/lab/repoA repoSSH
darcs clone ssh://darcs-lab//root/lab/repoA repoSSH2

Copying patches, to get lazy repository hit ctrl-C...
Finished cloning.

单斜杠会失败（重要）：

darcs clone ssh://darcs-lab/root/lab/repoA repoSSH

Not a repository: ssh://darcs-lab/root/lab/repoA:
The program "scp -- darcs-lab:root/lab/repoA/_darcs/format ./darcs98281-1" failed with error: ...
scp: root/lab/repoA/_darcs/format: No such file or directory

单斜杠被当作 URL 分隔符吃掉，远端路径变成相对路径 root/lab/...。要么用 host:/abs/path，要么 ssh://host//abs/path。

5.3 DARCS_SSH 实测异常

按文档 DARCS_SSH 应可替换 SSH 客户端，但实测：

DARCS_SSH=/bin/false darcs clone darcs-lab:/root/lab/repoA /root/lab/failclone2

Copying patches, to get lazy repository hit ctrl-C...
We have conflicts!
Affected paths:
./hello.txt

克隆仍然完成，说明该变量未拦截 2.18.5 的 transfer-mode/scp 回退路径。生产环境请用 ~/.ssh/config 管理别名、端口与密钥，不要依赖 DARCS_SSH 做访问控制。

六、缓存

Darcs 有两级缓存：

  • 全局缓存：~/.cache/darcs/（实测 3.3 MB，分 inventories/、patches/、pristine.hashed/，桶式两级目录）；
  • 仓库缓存：_darcs/ 内部，darcs show repo 会显示 Cache: thisrepo:..., cache:/root/.cache/darcs。

清理与迁移：

darcs optimize cache

Migrating global cache to bucketed format.
Done making bucketed cache!
Done cleaning global cache!

说明：Darcs 2.18.5 没有 darcs cache 子命令（执行报 No such command 'cache'），缓存操作统一走 darcs optimize cache。缓存目录随 $HOME 变化，用 systemd 或 cron 跑 Darcs 时要确保 HOME 正确，否则缓存会落到 /root 或空目录。

七、推荐配置模板

~/.darcs/defaults：

# 提交时跑测试；作者从 ~/.darcs/author 读取
record --test
# 日志默认显示最近 20 条
log --last 20

_darcs/prefs/boring：

.*\.o$
.*\.pyc$
^dist/
^\.stack-work/

_darcs/prefs/binaries：

.*\.(png|jpg|gif|zip|gz|pdf)$

~/.ssh/config：

Host darcs-prod
    HostName git.example.com
    Port 2222
    User deploy
    IdentityFile ~/.ssh/id_ed25519

八、排障实录

1）*.o 写进 boring 完全不生效

回显 Warning: Ignored invalid boring regex: *.o，随后照常显示变更。改用 .*\.o$。同理 binaries 也必须写正则。

2）defaults 里加了引号，作者字段带引号

record --author "ops <ops@example.com>" 会把引号一起存进作者，日志显示 Author: "ops ..."。去掉引号即可。

3）用户级 defaults 改了没反应

先看仓库是否有 _darcs/prefs/defaults——仓库级优先。用 darcs log --last 5 直接覆盖验证。

4）SSH URL 单斜杠导致 scp: No such file or directory

改用 host:/abs/path 或 ssh://host//abs/path；同时确认远端 darcs 在非交互 PATH 中（ssh host 'which darcs'）。

5）DARCS_SSH 设了不生效

见 5.3。改用 SSH 配置文件；若要做访问控制，在 sshd_config 的 command=/AuthorizedKeysCommand 层做，而不是客户端变量。

6）缓存不增长/找不到

检查运行用户的 HOME 与 ~/.cache/darcs；darcs show repo 的 Cache: 行是实际路径。批量任务/定时任务里常见 HOME=/ 导致缓存落错位置。

九、验收清单

darcs show repo                    # 看 Format / Cache / PatchIndex
cat _darcs/prefs/defaultrepo       # 默认远端
darcs optimize cache               # 缓存可清理
darcs help environment | head -20  # 环境变量清单

配置改完务必用一个临时仓库回归一次 record → log → push，避免 defaults 语法错误影响团队提交。下一篇：《Darcs 2.18.5 常用 CLI 命令详解》。