Linux من الصفر إلى السيرفر الأدلة التقنية

ملفات الإعداد Dotfiles: انقل طرفيتك إلى أي جهاز

نحفظ إعداد Bash وGit وtmux في مستودع واحد ونطبقه على جهاز جديد بأمر واحد، ونقارن GNU Stow والمستودع العاري وchezmoi بقوالبه وأسراره المشفرة، مع توكن حقيقي التقطه gitleaks قبل أن يدخل المستودع.

ملفات الإعداد Dotfiles: انقل طرفيتك إلى أي جهاز

إذا قضيت وقتاً في ضبط طرفيتك، فاختصارات Bash التي تعودت عليها، وإعداد Git باسمك وبريدك، وملف tmux الذي يجعل الشاشة كما تحب، ثم استلمت حاسوباً جديداً من العمل أو أنشأت سيرفراً جديداً أو فتحت Container للتطوير، فأنت تعرف الشعور: ساعة أو أكثر تحاول فيها أن تتذكر ما الذي كان في الجهاز القديم، وتنسخ ملفاً من هنا وسطراً من هناك، وبعد أسبوع تكتشف أن الاختصار الذي تستخدمه كل يوم لم ينتقل. وإذا كان لديك ثلاثة أجهزة فالمشكلة أسوأ، لأن كل واحد منها ينحرف عن الآخر مع كل تعديل صغير تفعله في واحد وتنسى أن تنقله إلى الباقي.

والحل الذي استقر عليه أغلب المطورين أن تعامل هذه الملفات كأي كود: تحفظها في مستودع Git واحد، ولها تاريخ ورسائل Commit، وتطبقها على أي جهاز جديد بأمر واحد. وهذه الملفات اسمها ملفات الإعداد Dotfiles، لأن أسماءها تبدأ بنقطة. وفي هذا المقال سوف نبني مستودعاً حقيقياً فيه إعداد Bash وGit وtmux، ثم نطبقه بأربع طرق، من سكربت روابط بسيط إلى GNU Stow إلى المستودع العاري Bare Repository إلى chezmoi، ونشغل كل طريقة على Container جديد لا يعرف عنا شيئاً، ونرى أين تفشل كل واحدة. وكل مخرج تراه هنا خرج من تشغيل حقيقي، بما في ذلك توكن GitHub كاد أن يدخل المستودع لولا أداة فحص الأسرار. وإذا كنت جديداً على Git فابدأ بمقال إدارة النسخ وGit للمبتدئين.

وسوف نناقش في هذا المقال ما يلي:

  • ما هي ملفات الإعداد، وأين تعيش، وما الذي يدخل المستودع وما الذي لا يدخله أبداً.
  • الطريقة البسيطة بالنسخ والروابط، ولماذا تمسح ملفاتك دون أن تخبرك.
  • GNU Stow: حزمة لكل برنامج، والتعارض مع ملف موجود، وخطر الخيار --adopt.
  • المستودع العاري Bare Repo: مجلدك الشخصي نفسه هو مجلد العمل.
  • chezmoi: القوالب Templates لكل جهاز، والسكربتات التي تعمل مرة واحدة، والتجاهل بحسب النظام.
  • الأسرار: خطأ حقيقي التقطه gitleaks، والتوكن من مدير كلمات المرور، والملفات المشفرة بأداة age.
  • جهاز جديد بأمر واحد، ونفس المستودع على Linux وmacOS وWSL وWindows، ثم جدول قرار وأخطاء شائعة.

ما هي ملفات الإعداد Dotfiles؟

في Linux وmacOS أي ملف يبدأ اسمه بنقطة لا يظهر في ls العادي، ولذلك اختارته البرامج منذ بدايات Unix لإعداداتها في مجلد المستخدم الشخصي، أو المنزل Home كما يسمى، فلا تزحم ما تراه كل يوم. ومنها ~/.bashrc الذي تقرؤه Bash عند فتح كل طرفية، و~/.gitconfig الذي يحمل اسمك وبريدك واختصارات Git، و~/.tmux.conf، و~/.ssh/config، و~/.vimrc. ومع كثرة هذه الملفات وضع مشروع freedesktop مواصفة XDG Base Directory التي تجمع إعداد البرامج الحديثة تحت مجلد واحد هو ~/.config، فتجد مثلاً ~/.config/gh/ لأداة GitHub CLI و~/.config/starship.toml لسطر الأوامر، ولذلك عندما نقول ملفات الإعداد فنحن نقصد الاثنين: الملفات التي تبدأ بنقطة في المنزل، وما تحت ~/.config.

وقبل أن تضع أي ملف في المستودع اسأل نفسك سؤالاً واحداً: هل أريد هذا الملف كما هو على كل جهاز، وهل يصح أن يقرأه غيري؟ والجدول التالي يجمع ما وصلنا إليه:

يدخل المستودعلا يدخل المستودعوالسبب
.bashrc و.zshrc و.profile.bash_historyالتاريخ فيه أوامر بكلمات مرور وعناوين داخلية
.gitconfig دون أسرار.git-credentials و.netrcملفات أسرار بالكامل
.tmux.conf و.vimrc و.config/starship.toml.cache و.local/shareبيانات تولدها البرامج، تتغير كل دقيقة وتكبر
.ssh/config.ssh/id_* المفاتيح الخاصةالمفتاح الخاص لا يخرج من الجهاز، ولكل جهاز مفتاحه
.config/gh/config.yml.config/gh/hosts.yml و.npmrc بتوكنفيها توكن، وسوف نرى كيف تنقلها بطريقة آمنة

ولاحظ الصف الأخير، فهو الذي يقع فيه أغلب الناس، لأن نفس المجلد فيه ملف إعداد عادي وملف بجانبه فيه توكن، ونسخ المجلد كله إلى المستودع يبدو أسهل خطوة في العالم. وسوف نرجع إليه في قسم الأسرار بتجربة حقيقية.

الطريقة البسيطة: النسخ ثم الروابط

أول ما يفعله أي أحد هو النسخ: scp ~/.bashrc server: أو ملف يرسله إلى نفسه، وهذا يعمل مرة واحدة ثم يبدأ الانحراف، فلا يوجد مكان واحد فيه النسخة الصحيحة، ولا تعرف ما الذي تغير ومتى. والخطوة التالية الطبيعية أن تضع الملفات في مستودع Git وتنشئ في المنزل روابط رمزية Symbolic Links تشير إليها، فأي تعديل تفعله في ~/.bashrc هو تعديل في المستودع نفسه، ويظهر في git diff. وكثيرون يكتبون لذلك سكربتاً من بضعة أسطر ln -sf، فجربنا هذا على Container جديد من Debian بعد أن نسخنا المستودع:

wc -l ~/.bashrc
ln -sf ~/dotfiles/bash/.bashrc ~/.bashrc
ln -sf ~/dotfiles/git/.gitconfig ~/.gitconfig
ls -l ~/.bashrc ~/.gitconfig
wc -l ~/.bashrc
19 /root/.bashrc
lrwxrwxrwx 1 root root 27 Nov 16 11:30 /root/.bashrc -> /root/dotfiles/bash/.bashrc
lrwxrwxrwx 1 root root 29 Nov 16 11:30 /root/.gitconfig -> /root/dotfiles/git/.gitconfig
14 /root/.bashrc

الروابط تعمل، ولكن انظر إلى السطر الأول والأخير: كان في الجهاز ملف .bashrc من 19 سطراً وضعه Debian، وبعد الأمر صار الرابط إلى ملفنا من 14 سطراً، والملف الأصلي اختفى دون أي نسخة احتياطية Backup ودون أي سؤال، لأن الخيار -f معناه «احذف ما في الطريق». وهذا مقبول في Container جديد، ولكنه على حاسوب عملت عليه سنة قد يمسح إعداداً لم تنقله بعد إلى المستودع. وهنا تأتي الأدوات التي سوف نراها: كل واحدة منها تحل هذه المشكلة بطريقة مختلفة.

أربع بطاقات لطرق وضع ملفات الإعداد: النسخ اليدوي بلا مصدر واحد، والروابط مع ln -s أو GNU Stow حيث الملف في المنزل رابط إلى المستودع، والمستودع العاري حيث المنزل نفسه مجلد العمل لـ Git، ومولد مثل chezmoi يصنع ملفاً مختلفاً لكل جهاز من قالب مع أسرار مشفرة، وتحتها سهم من مستودع Git إلى الملفات في المنزل
كل الطرق تبدأ من Git، والفرق في كيف يصل الملف إلى المنزل

تجهيز المختبر: حاسوب قديم وسيرفر Git وأجهزة جديدة

أردنا أن نجرب الشيء الذي يهم فعلاً، أي جهازاً جديداً لم نلمسه من قبل، لذلك جهزنا ثلاثة أنواع من الأجهزة: «الحاسوب القديم» الذي نكتب عليه المستودع، وفيه Git وStow وchezmoi وage وpass وgitleaks، وسيرفر Git صغير يقدم المستودعات بالبروتوكول git://، وContainers جديدة من debian:trixie-slim كما هي، نحذفها بعد كل تجربة. وهذا ملف الحاسوب القديم:

# the "old laptop": where the dotfiles repo is written (git, stow, chezmoi, age, pass, gitleaks)
FROM debian:trixie-slim
RUN apt-get update && apt-get install -y --no-install-recommends git stow curl ca-certificates gnupg pass age tmux less procps \
 && rm -rf /var/lib/apt/lists/* \
 && sh -c "$(curl -fsLS get.chezmoi.io)" -- -b /usr/local/bin -t v2.74.1 \
 && curl -fsSL https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz | tar -xz -C /usr/local/bin gitleaks \
 && useradd -m -s /bin/bash dev
USER dev
WORKDIR /home/dev

ولاحظ أن chezmoi وgitleaks لا يأتيان من مستودع Debian: الأول غير موجود فيه، والثاني موجود بالإصدار 8.16 وهو قديم، لذلك نزلنا الإصدارين الرسميين 2.74.1 و8.30.1. وأما سيرفر Git فهو git daemon يقدم مجلداً مشتركاً، ويكتب فيه الحاسوب القديم عبر نفس المجلد:

#!/bin/sh
# starts the lab: a git server (git://lnxf-git/) and the old laptop that pushes to it through a shared volume
set -e
docker network create lnxf-dot
docker volume create lnxf-dot-repos
docker run --rm -v lnxf-dot-repos:/srv/git debian:trixie-slim chown 1000:1000 /srv/git
docker run -d --name lnxf-git --hostname git --network lnxf-dot -v lnxf-dot-repos:/srv/git lnxf-dot-git:1
docker run -d --name lnxf-laptop --hostname laptop --network lnxf-dot -v lnxf-dot-repos:/srv/git lnxf-dot-laptop:1 sleep infinity

وأول مشكلة واجهتنا كانت هنا: سيرفر Git رفض أن يقدم المستودع وكتب في سجله fatal: detected dubious ownership in repository at '/srv/git/dotfiles.git'، لأن git daemon كان يعمل بالمستخدم root والمستودع ملك المستخدم 1000، وGit منذ 2022 يرفض العمل في مستودع يملكه مستخدم آخر لأسباب أمنية. والحل كان تشغيل الخدمة بنفس المستخدم في ملف الـ Image، بالسطر USER git لمستخدم رقمه 1000، لا إضافة استثناء safe.directory عام.

والمستودع نفسه بسيط، وملف .bashrc فيه يستحق النظر لأن فيه فكرة سوف نحتاجها في قسم الأسرار:

# ~/.bashrc from the dotfiles repo
case $- in *i*) ;; *) return ;; esac       # interactive shells only

HISTSIZE=50000
HISTFILESIZE=100000
HISTCONTROL=ignoreboth:erasedups
shopt -s histappend checkwinsize

alias ll='ls -lah --color=auto'
alias gs='git status -sb'
export EDITOR=vim

# machine-specific settings and secrets live here, never in git
[ -f ~/.bashrc.local ] && . ~/.bashrc.local

والسطر الأخير هو المهم: كل ما يخص جهازاً واحداً، أو فيه سر، يوضع في ملف ~/.bashrc.local لا يدخل المستودع، والملف المشترك يقرؤه إن وجد. وهذه أبسط طريقة لفصل المشترك عن الخاص، وتعمل مع كل الأدوات. والملفان الآخران هما .gitconfig بالاسم والبريد وبعض الاختصارات، و.tmux.conf الذي شرحناه سطراً سطراً في مقال الجلسات مع tmux في هذه المرحلة.

GNU Stow: مجلد لكل برنامج، ورابط لكل ملف

GNU Stow أداة قديمة كتبت أصلاً لإدارة البرامج المثبتة من المصدر في /usr/local، وفكرتها أن كل برنامج في مجلد خاص به يسمى حزمة Package، وأن Stow ينشئ في المجلد الهدف Target رابطاً لكل ملف في الحزمة بنفس المسار النسبي. وهذه الفكرة نفسها تناسب ملفات الإعداد تماماً، فصار المستودع عندنا كما يلي، وكل مجلد في أعلاه حزمة:

dotfiles/
├── bash/.bashrc
├── git/.gitconfig
├── tmux/.tmux.conf
├── install.sh
└── README.md

والأمر stow -t ~ bash git tmux يعني: اربط محتوى الحزم الثلاث داخل المنزل. ولاحظ أن الحزمة bash فيها الملف .bashrc مباشرة، فيصبح الرابط ~/.bashrc، ولو كان فيها .config/foo/bar.toml لأنشأ Stow المجلدات وصار الرابط في ~/.config/foo/bar.toml. والمصدر الرسمي للأداة مستودع GNU Stow الذي يديره Adam Spiers. وشغلناه أول مرة على الحاسوب القديم الذي فيه ملف .bashrc من Debian:

$ stow -v -t /home/dev bash git tmux
LINK: .gitconfig => dotfiles/git/.gitconfig
LINK: .tmux.conf => dotfiles/tmux/.tmux.conf
WARNING! stowing bash would cause conflicts:
  * cannot stow dotfiles/bash/.bashrc over existing target .bashrc since neither a link nor a directory and --adopt not specified
All operations aborted.
$ ls -la /home/dev | grep -c -- '->'
0

وهذا عكس ما فعله ln -sf تماماً، وهو السلوك الصحيح: وجد Stow ملفاً حقيقياً في مكان الرابط، فرفض أن يكتب فوقه، ولاحظ أنه ألغى العملية كلها، فحتى الرابطان اللذان طبع LINK لهما لم ينشآ، والعدد صفر. فلا تبقى في حالة نصف مطبقة. والرسالة نفسها تقترح الخيار --adopt، وهنا الفخ الذي يقع فيه كثيرون، فجربناه:

$ stow -v --adopt -t /home/dev bash git tmux
MV: .bashrc -> dotfiles/bash/.bashrc
LINK: .bashrc => dotfiles/bash/.bashrc
LINK: .gitconfig => dotfiles/git/.gitconfig
LINK: .tmux.conf => dotfiles/tmux/.tmux.conf
$ git status --short
 M bash/.bashrc
$ git diff --stat
 bash/.bashrc | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 110 insertions(+), 11 deletions(-)

في المخرج أعلاه لاحظ التالي:

  • السطر MV يقول إن Stow نقل ملف Debian الموجود إلى داخل المستودع فوق ملفنا، ثم أنشأ الرابط. أي أن «تبني» الملف معناه أن الملف الموجود في المنزل هو الذي يفوز.
  • git status يبين أن ملفنا تغير، وgit diff يبين 110 أسطر جديدة و11 محذوفة، فملفنا المكتوب بعناية صار ملف Debian الافتراضي.
  • الخيار مفيد في حالة واحدة: عندما تبدأ المستودع لأول مرة من ملفات حاسوبك وتريدها هي بالضبط. وفي كل حالة أخرى يجب أن تتبعه مباشرة بقراءة git diff.

ولأن الملف ما زال في Git فالرجوع سهل: git checkout -- bash/.bashrc أعاد ملفنا، والرابط أصلاً يشير إليه، فصار ~/.bashrc ملفنا من 392 بايت يبدأ بالسطر # ~/.bashrc from the dotfiles repo. والدرس أن Stow آمن افتراضياً، وأن الخيار الذي يجعله يعمل بصمت هو الذي يحتاج الحذر.

المستودع ~/dotfiles بحزمه الثلاث bash وgit وtmux وأسهم من كل ملف إلى رابط في المنزل بعد الأمر stow -t ~ bash git tmux، وتحته حالتان: ملف .bashrc حقيقي موجود يوقف كل شيء برسالة cannot stow over existing target، ومع --adopt ينقل ملف Debian إلى المستودع فيظهر git diff بـ 110 أسطر جديدة و11 محذوفة
Stow يرفض الكتابة فوق ملف حقيقي، و--adopt يقلب الاتجاه

سكربت تثبيت يأخذ نسخة احتياطية

على جهاز جديد لا نريد أن نقرأ git diff في كل مرة، وإنما أمراً واحداً يعمل. لذلك أضفنا إلى المستودع سكربت install.sh ينقل أي ملف حقيقي في الطريق إلى مجلد نسخ احتياطية بتاريخ، ثم يشغل Stow:

#!/bin/sh
# install.sh: links the stow packages into $HOME; an existing real file is moved to ~/.dotfiles-backup first
set -e
cd "$(dirname "$0")"
backup="$HOME/.dotfiles-backup/$(date +%Y%m%d-%H%M%S)"
for pkg in bash git tmux; do
  for f in $(cd "$pkg" && find . -type f | sed 's|^\./||'); do
    if [ -e "$HOME/$f" ] && [ ! -L "$HOME/$f" ]; then
      mkdir -p "$backup/$(dirname "$f")"
      mv "$HOME/$f" "$backup/$f"
      echo "backup: ~/$f -> $backup/$f"
    fi
  done
done
stow -v -t "$HOME" bash git tmux

ثم شغلنا Container جديداً من debian:trixie-slim، وكتبنا فيه أمراً واحداً يثبت Git وStow ويجلب المستودع ويطبقه، وقسنا الوقت:

apt-get update -qq && apt-get install -y -qq --no-install-recommends git stow ca-certificates >/dev/null 2>&1 \
  && git clone -q git://git/dotfiles.git ~/.dotfiles && ~/.dotfiles/install.sh
backup: ~/.bashrc -> /root/.dotfiles-backup/20261116-111522/.bashrc
LINK: .bashrc => .dotfiles/bash/.bashrc
LINK: .gitconfig => .dotfiles/git/.gitconfig
LINK: .tmux.conf => .dotfiles/tmux/.tmux.conf
took 26 s
alias gs='git status -sb'
HISTSIZE=50000

26 ثانية من Container فارغ إلى طرفية فيها اختصاراتنا، وأغلبها في apt-get، وملف Debian محفوظ في مجلد النسخ الاحتياطية إذا احتجناه. والسطران الأخيران من Bash تفاعلية جديدة يؤكدان أنها قرأت ملفنا. ولاحظ أننا نسخنا المستودع إلى ~/.dotfiles بنقطة، فلا يظهر في المنزل، والروابط صارت نسبية مثل .dotfiles/bash/.bashrc.

مشكلة حقيقية: ملفات الإعداد صارت قابلة للتنفيذ

كتبنا ملفات المستودع على Windows ثم نسخناها إلى الحاسوب القديم، وبعد أيام لاحظنا شيئاً غريباً في git ls-files -s، وهو الأمر الذي يعرض صلاحيات كل ملف كما يحفظها Git:

100644 0	.gitignore
100755 0	README.md
100755 0	bash/.bashrc
100755 0	git/.gitconfig
100755 0	install.sh
100755 0	tmux/.tmux.conf

الرقم 100755 يعني ملفاً قابلاً للتنفيذ، وهذا صحيح لـ install.sh فقط. والسبب أن نظام الملفات في Windows لا يعرف صلاحية التنفيذ، فالملفات التي تأتي منه عبر مجلد مشترك أو نسخ تظهر في Linux غالباً بالصلاحيات 755. والضرر هنا صغير، ولكن كل جهاز يطبق المستودع سوف يحصل على .bashrc قابل للتنفيذ، وأداة مثل chezmoi تحفظ هذه الصلاحية في اسم الملف كما سوف نرى. والإصلاح أمر واحد ثم Commit:

$ chmod -x README.md bash/.bashrc git/.gitconfig tmux/.tmux.conf
$ git diff --summary
 mode change 100755 => 100644 README.md
 mode change 100755 => 100644 bash/.bashrc
 mode change 100755 => 100644 git/.gitconfig
 mode change 100755 => 100644 tmux/.tmux.conf

المستودع العاري Bare Repo: المنزل نفسه هو مجلد العمل

في 2016 كتب أحد المستخدمين في نقاش على Hacker News طريقة لا تحتاج أي أداة غير Git ولا أي رابط، ثم انتشرت بعد أن شرحتها Atlassian في درس عن الـ Dotfiles. والفكرة أن المستودع العادي فيه شيئان: مجلد .git الذي يحفظ التاريخ، ومجلد العمل Work Tree الذي فيه الملفات. والمستودع العاري Bare Repository هو المجلد الأول فقط، وتقول لـ Git عند كل أمر إن مجلد العمل هو المنزل كله. وجربناها في منزل تجريبي فيه ملفاتنا وبعض الملفات التي تولدها البرامج:

$ git init -q --bare /tmp/bare-home/.cfg
$ alias 'cfg=git --git-dir=/tmp/bare-home/.cfg --work-tree=/tmp/bare-home'
$ cfg status --short
?? .bash_history
?? .bashrc
?? .cache/
?? .cfg/
?? .local/
?? .tmux.conf
$ cfg config status.showUntrackedFiles no
$ cfg status --short
$ cfg add .bashrc .tmux.conf
$ cfg commit -qm 'bare repo'
$ cfg ls-files
.bashrc
.tmux.conf

في المخرج أعلاه لاحظ التالي:

  • أول status يعرض كل ما في المنزل كملفات غير متتبعة، بما فيها .bash_history و.cache، وعلى منزل حقيقي تكون القائمة بالمئات. ولذلك أول إعداد في هذه الطريقة هو status.showUntrackedFiles no، وبعده لا يعرض status إلا الملفات التي أضفتها بنفسك.
  • هذا الإعداد نفسه هو خطرها: إذا كتبت cfg add . مرة واحدة بالخطأ فقد أضفت المنزل كله، وفيه التاريخ والمفاتيح. فأضف الملفات بأسمائها دائماً.
  • الاسم المستعار Alias هو ما يجعلها عملية، وتضعه في .bashrc نفسه. وفي سكربت التجربة كتبنا الأمر كاملاً في كل سطر لأن Bash لا تستخدم الأسماء المستعارة في السكربتات، واختصرناه هنا بالاسم cfg حتى يسهل قراءة المخرج.

ثم نسخنا هذا المستودع إلى منزل جديد فيه ملف .bashrc من Debian، فظهرت نفس مشكلة Stow بشكل آخر:

$ git clone -q --bare /tmp/bare-home/.cfg /tmp/new-home/.cfg
$ git --git-dir=/tmp/new-home/.cfg --work-tree=/tmp/new-home checkout
error: The following untracked working tree files would be overwritten by checkout:
	.bashrc
Please move or remove them before you switch branches.
Aborting

وGit هنا آمن مثل Stow: لا يكتب فوق ملف لا يعرفه، وتحتاج أن تنقل الملفات المتعارضة قبل checkout، وهو ما يفعله سكربت البداية في درس Atlassian. ونقاط القوة في هذه الطريقة أنها لا تحتاج إلا Git الموجود في كل مكان، ولا روابط فتعمل على Windows أيضاً. ونقاط الضعف أنه لا توجد طريقة لملف يختلف بين جهازين إلا الفروع Branches، ولا يوجد أي حل للأسرار، وأمر add واحد خاطئ يكفي ليدخل المنزل كله المستودع.

chezmoi: ملف مختلف لكل جهاز من نفس المصدر

كل الطرق السابقة تفترض أن الملف واحد على كل الأجهزة، والواقع غير ذلك: بريدك في Git على حاسوب العمل غيره على حاسوبك الشخصي، وحاسوب العمل يحتاج بروكسي لا يحتاجه غيره، وcredential.helper على Windows غيره على Linux، وبعض الملفات لا معنى لها إلا على نظام واحد. وأداة chezmoi، واسمها من الفرنسية «في بيتي»، كتبها Tom Payne بلغة Go، وتأتي كملف تنفيذي واحد، وتعالج هذا بفكرة مختلفة: لا روابط، وإنما مجلد مصدر Source في ~/.local/share/chezmoi هو مستودع Git، وأمر chezmoi apply يحسب من المصدر ما يجب أن يكون عليه كل ملف في هذا الجهاز ثم يكتبه.

وانتقلنا إليها من مستودع Stow نفسه: أزلنا الروابط بالأمر stow -D، ونسخنا الملفات إلى المنزل، ثم أضفناها إلى chezmoi:

$ stow -v -D -t /home/dev bash git tmux
UNLINK: .bashrc
UNLINK: .gitconfig
UNLINK: .tmux.conf
$ cp bash/.bashrc git/.gitconfig tmux/.tmux.conf /home/dev/
$ chezmoi init
$ chezmoi add /home/dev/.bashrc /home/dev/.tmux.conf
$ chezmoi add --template /home/dev/.gitconfig
$ ls /home/dev/.local/share/chezmoi
executable_dot_bashrc
executable_dot_gitconfig.tmpl
executable_dot_tmux.conf

وهنا عادت مشكلة صلاحية التنفيذ، لأن النسخ حدث قبل أن نصلحها في المستودع، وظهرت بوضوح أكثر: chezmoi يحفظ صلاحيات الملف في اسمه، فالبادئة executable_ تعني أنه سوف ينشئ .bashrc قابلاً للتنفيذ على كل جهاز. فأصلحنا الصلاحيات وأعدنا الإضافة:

$ chmod 644 /home/dev/.bashrc /home/dev/.gitconfig /home/dev/.tmux.conf
$ chezmoi forget --force /home/dev/.bashrc /home/dev/.gitconfig /home/dev/.tmux.conf
$ chezmoi add /home/dev/.bashrc /home/dev/.tmux.conf
$ chezmoi add --template /home/dev/.gitconfig
$ ls /home/dev/.local/share/chezmoi
dot_bashrc
dot_gitconfig.tmpl
dot_tmux.conf

وهذه البادئات هي لغة chezmoi كلها، فاسم الملف في المصدر يحمل كل التعليمات: dot_ تصبح نقطة في البداية، وprivate_ صلاحيات 600، وencrypted_ ملف مشفر، وrun_once_ سكربت يعمل مرة واحدة، والنهاية .tmpl تعني أنه قالب. والقائمة الكاملة في صفحة Source State Attributes، والصورة التالية تجمع ما استخدمناه في هذا المقال:

جدول لأسماء الملفات في مصدر chezmoi وما يحدث لكل منها: dot_bashrc ينسخ إلى ~/.bashrc، وdot_gitconfig.tmpl قالب يقرأ البريد وwork ونظام التشغيل، وencrypted_private_dot_npmrc.age يفك تشفيره بالمفتاح key.txt إلى ~/.npmrc بصلاحيات 600، وprivate_hosts.yml.tmpl يطلب التوكن من pass، وrun_once_before_10-packages.sh.tmpl ينفذ مرة قبل الملفات، و.chezmoiignore يقرر ما لا ينشأ على هذا الجهاز، وتحته بطاقتا البيانات والحالة
اسم الملف في المصدر هو التعليمات

القوالب Templates والبيانات Data

القالب ملف عادي فيه أجزاء بين {{ }} بلغة قوالب Go، تقرأ بيانات الجهاز. وبعض البيانات يعرفها chezmoi وحده، مثل .chezmoi.os و.chezmoi.hostname و.chezmoi.osRelease، وبعضها نسأل عنه مرة واحدة عند أول init في ملف خاص اسمه .chezmoi.toml.tmpl:

{{- $email := promptStringOnce . "email" "Git email" -}}
{{- $work := promptBoolOnce . "work" "Is this a work machine" -}}
encryption = "age"

[age]
    identity = "~/.config/chezmoi/key.txt"
    recipient = "age12f53e8lkt6yk0sthx3s8kqgnymusa0lazkawyr40jfklcq20js3qxz0a7x"

[data]
    name = "Dev Example"
    email = {{ $email | quote }}
    work = {{ $work }}

والدالة promptStringOnce تسأل عن البريد إذا لم يكن محفوظاً، ثم تحفظ الجواب في إعداد الجهاز فلا تسأل مرة أخرى. ولأننا نشغل كل شيء بسكربتات، حاولنا أن نعطيها الجواب في سطر الأمر باسم المفتاح، فحصلنا على هذا:

$ chezmoi init --promptString [email protected] --promptBool work=false
Git email?
chezmoi: template: chezmoi.toml:1:14: executing "chezmoi.toml" at <promptStringOnce . "email" "Git email">: error calling promptStringOnce: could not open a new TTY: open /dev/tty: no such device or address

الخطأ يقول إنه لم يجد طرفية ليسأل فيها، أي أنه تجاهل ما أعطيناه. والسبب كما يشرح توثيق الأمر init أن القيمة تربط بنص السؤال نفسه لا باسم المفتاح، بالشكل prompt=value. فأعدنا الأمر بنص السؤال:

$ chezmoi init --promptString 'Git [email protected]' --promptBool 'Is this a work machine=false'
$ cat /home/dev/.config/chezmoi/chezmoi.toml
encryption = "age"
...
[data]
    name = "Dev Example"
    email = "[email protected]"
    work = false

وهذا مهم لما بعده، لأن الأمر الواحد الذي يجهز جهازاً جديداً لا يجد من يجيب على الأسئلة إذا كان يعمل في سكربت أو في بناء Image. ثم حولنا .gitconfig إلى قالب يقرأ هذه البيانات ونظام التشغيل:

[user]
	name = {{ .name }}
	email = {{ .email }}
[init]
	defaultBranch = main
[pull]
	rebase = true
{{- if eq .chezmoi.os "windows" }}
[core]
	autocrlf = true
[credential]
	helper = manager
{{- else if eq .chezmoi.os "darwin" }}
[credential]
	helper = osxkeychain
{{- else }}
[credential]
	helper = cache --timeout=3600
{{- end }}
{{- if .work }}
[http]
	proxy = http://proxy.corp.example:3128
{{- end }}
[alias]
	lg = log --oneline --graph --decorate -15

وقبل أن تكتب أي شيء، الأمر chezmoi diff يعرض الفرق بين ما في المنزل وما سوف يكتبه، وهذا ما ظهر لنا على الحاسوب القديم:

$ chezmoi diff /home/dev/.gitconfig
--- a/.gitconfig
+++ b/.gitconfig
@@ -5,5 +5,7 @@ [init]
 	defaultBranch = main
 [pull]
 	rebase = true
+[credential]
+	helper = cache --timeout=3600
 [alias]
 	lg = log --oneline --graph --decorate -15

أضاف القالب سطري Linux فقط، ولم يضف البروكسي لأن work قيمتها false، وعلى Windows سوف نرى بعد قليل أن نفس القالب أخرج ملفاً آخر. واجعل chezmoi diff عادة قبل كل apply على جهاز فيه إعداد لا تعرفه، لأنه الأمر الوحيد الذي يريك ما سوف يتغير قبل أن يتغير.

سكربتات تعمل مرة واحدة run_once

نقل الإعداد لا يكفي إذا كانت البرامج نفسها غير مثبتة، فلا فائدة من .tmux.conf على جهاز بلا tmux. وchezmoi يشغل أي ملف في المصدر يبدأ بالكلمة run_ كسكربت، ومع once يشغله مرة واحدة لكل محتوى، ومع before يشغله قبل كتابة الملفات، كما يشرح دليل السكربتات. وهذا سكربتنا، وهو قالب أيضاً حتى يختار مدير الحزم بحسب التوزيعة:

{{- if eq .chezmoi.os "linux" -}}
#!/bin/sh
# runs once per machine, before chezmoi writes the files: installs only what is missing
set -e
missing=""
for c in tmux less vi; do command -v "$c" >/dev/null || missing="$missing $c"; done
[ -z "$missing" ] && { echo "packages: nothing to install"; exit 0; }
SUDO=""; [ "$(id -u)" -ne 0 ] && SUDO=sudo
{{ if eq .chezmoi.osRelease.id "debian" "ubuntu" -}}
$SUDO apt-get update -qq
$SUDO apt-get install -y -qq --no-install-recommends tmux less vim-tiny >/dev/null
{{ else if eq .chezmoi.osRelease.id "fedora" -}}
$SUDO dnf install -y tmux less vim-minimal
{{ end -}}
echo "packages installed on {{ .chezmoi.osRelease.prettyName }}:$missing"
{{ end -}}

وفي السكربت أعلاه لاحظ التالي:

  • القالب كله داخل شرط linux، فعلى Windows وmacOS يخرج ملفاً فارغاً، وchezmoi لا يشغل السكربت الفارغ.
  • eq .chezmoi.osRelease.id "debian" "ubuntu" صحيحة إذا كانت القيمة الأولى تساوي أياً من الباقي، فسطر واحد يغطي التوزيعتين.
  • السكربت يبحث أولاً عما ينقص ولا يثبت شيئاً إذا كان كل شيء موجوداً، وهذا ما يجعله آمناً لو أعاده chezmoi لأي سبب.
  • يستخدم sudo فقط عندما لا يعمل بالمستخدم root، لأن Container جديداً يعمل غالباً بالمستخدم root ولا يوجد فيه sudo.

وفي أول تشغيل على الحاسوب القديم واجهنا مشكلة تستحق أن تعرفها قبل أن تكتب سكربتك الأول. فالحاسوب القديم كان ينقصه vi، والمستخدم dev ليس root ولا يوجد sudo:

/tmp/3966954051.10-packages.sh: 8: sudo: not found
chezmoi: 10-packages.sh: exit status 127
exit 1
ls: cannot access '/home/dev/.npmrc': No such file or directory

فشل السكربت، ومعه توقف apply كله ولم يكتب أي ملف، لأن السكربت من نوع before. وهذا سلوك مقصود، فلا معنى لأن تكتب الإعداد إذا فشل ما يسبقه، وchezmoi لا يسجل السكربت كمنفذ إلا إذا نجح، فيعيده في التطبيق التالي. والدرس: اجعل سكربت run_once يعرف متى لا يستطيع العمل، ويخرج برسالة واضحة، أو يتخطى ما لا يقدر عليه إذا لم يكن ضرورياً. وبعد تثبيت vim-tiny بالمستخدم root نجح التطبيق وكتب الملفات، وظهر في المخرج packages: nothing to install.

ملفات لبعض الأجهزة فقط .chezmoiignore

بعض الملفات لا مكان لها على كل الأجهزة، مثل ملف إعداد PowerShell على Linux. والملف .chezmoiignore قائمة بما لا ينشئه chezmoi، وهو قالب أيضاً كما تشرح صفحته في التوثيق، فيقرر بحسب الجهاز:

README.md
{{- if ne .chezmoi.os "windows" }}
Documents
{{- end }}
{{- if not (lookPath "pass") }}
.config/gh/hosts.yml
{{- end }}

والشرط الثاني فيه فكرة مفيدة: الدالة lookPath تبحث عن برنامج في PATH، فإذا لم يكن مدير كلمات المرور pass موجوداً على هذا الجهاز لا يحاول chezmoi إنشاء الملف الذي يحتاجه، بدلاً من أن يفشل التطبيق كله كما رأينا مع السكربت.

الأسرار Secrets: أين يذهب التوكن؟

ملفات الإعداد مليئة بالأسرار دون أن تنتبه: ~/.npmrc فيه توكن النشر، و~/.config/gh/hosts.yml فيه توكن GitHub CLI، و~/.netrc فيه كلمات مرور. ومستودع الإعداد غالباً عام على GitHub حتى تجلبه بسهولة، وهنا الخطر، فقد وجدت دراسة How Bad Can It Git? المنشورة في مؤتمر NDSS سنة 2019 أن تسرب الأسرار في المستودعات العامة يصيب أكثر من 100,000 مستودع، وأن آلافاً من الأسرار الجديدة تتسرب كل يوم. ولذلك القاعدة في هذا القسم واحدة: السر لا يدخل Git كنص واضح أبداً، وسوف نرى ثلاث طرق لتحقيقها، ثم الحارس الذي يمسك الخطأ عندما تنسى.

الخطأ الذي التقطه gitleaks

أردنا أن ننقل إعداد GitHub CLI إلى كل الأجهزة، فنسخنا المجلد ~/.config/gh كله إلى حزمة جديدة في مستودع Stow، وهذا بالضبط ما يفعله أي أحد مستعجل:

$ mkdir -p gh/.config
$ cp -r /home/dev/.config/gh gh/.config/
$ git add -A
$ git commit -qm 'gh cli config'
$ git log --oneline -1 --stat
7f99310 gh cli config
 gh/.config/gh/config.yml | 3 +++
 gh/.config/gh/hosts.yml  | 4 ++++

الملف hosts.yml فيه توكن OAuth يبدأ بالحروف gho_، وهي بادئة وضعتها GitHub لكل نوع من توكناتها حتى يسهل اكتشافها كما شرحت في مقالها عن صيغ التوكنات. وقبل أن ندفع Push شغلنا gitleaks على تاريخ المستودع:

$ gitleaks git --no-banner --redact -v .
Finding:     oauth_token: REDACTED
Secret:      REDACTED
RuleID:      github-oauth
Entropy:     4.703056
File:        gh/.config/gh/hosts.yml
Line:        3
Commit:      7f993108f56a17d30613fce54b2bde802caf6f2d
Author:      Dev Example
...
INF 3 commits scanned.
WRN leaks found: 1
exit code: 1

وجد gitleaks التوكن بالقاعدة github-oauth في السطر 3، وأخفى قيمته في المخرج بالخيار --redact حتى لا يتسرب مرة ثانية في سجل الأداة نفسها. ولأن الـ Commit لم يخرج من الجهاز بعد، كان الإصلاح سهلاً: git reset HEAD~1 يلغي الـ Commit ويبقي الملفات. ولو كنا دفعناه فلا يكفي أي تنظيف للتاريخ، وأول خطوة إلغاء التوكن من GitHub وإصدار غيره، وقد فصلنا خطة الاستجابة كاملة في مقال اكتشاف الأسرار المسربة مع gitleaks وTruffleHog.

ولكن الفحص بعد الـ Commit يعتمد على أن تتذكر تشغيله، لذلك أضفنا خطافاً Hook يشغل gitleaks على الملفات المضافة قبل كل Commit، ثم كررنا نفس الخطأ عمداً:

$ printf '#!/bin/sh\nexec gitleaks git --pre-commit --staged --no-banner --redact -v .\n' > .git/hooks/pre-commit
$ chmod +x .git/hooks/pre-commit
$ git add -A
$ git commit -qm 'gh cli config'
Finding:     oauth_token: REDACTED
RuleID:      github-oauth
File:        gh/.config/gh/hosts.yml
...
WRN leaks found: 1
commit exit code: 1
$ git log --oneline -1
582e24f install.sh with backup

هذه المرة لم يحدث الـ Commit أصلاً، وآخر Commit ما زال السابق. ثم أخرجنا hosts.yml من الإضافة، وأضفناه إلى .gitignore، فدخل config.yml وحده ومر الخطاف برسالة no leaks found. وانتبه إلى أن الخطاف في .git/hooks لا ينتقل مع المستودع، فعلى كل جهاز تحتاج أن تضعه من جديد، أو تستخدم إطار pre-commit الذي شرحناه في مقال Git Hooks مع pre-commit فيصبح جزءاً من المستودع.

والآن نعرف ما لا نريده. والسؤال الحقيقي هو: كيف يصل التوكن إلى الجهاز الجديد إذا لم يكن في المستودع؟

ثلاث طرق للسر في مستودع الإعداد: مدير كلمات المرور حيث القالب يطلب السر عند التطبيق بالسطر pass github/dev-example، وملف مشفر بـ age يبدأ بـ BEGIN AGE ENCRYPTED FILE ويحتاج المفتاح الخاص على كل جهاز، وملف محلي خارج Git مثل ~/.bashrc.local، وتحتها بطاقة الحارس gitleaks الذي التقط توكن github-oauth ورفض Commit برمز خروج 1
ثلاثة أماكن آمنة للسر، وحارس قبل كل Commit

الطريقة الأولى: التوكن من مدير كلمات المرور

إذا كان لديك مدير كلمات مرور على كل جهاز، فالأفضل أن يبقى السر فيه، ويكون في المستودع قالب يطلبه عند التطبيق. وchezmoi يدعم أغلب المديرين المعروفة، مثل Bitwarden و1Password وKeePassXC، والقائمة في دليل مديري كلمات المرور. وفي المختبر استخدمنا pass لأنه يعمل في الطرفية ويحفظ كل سر كملف مشفر بمفتاح GPG، فوضعنا التوكن فيه، ثم كتبنا القالب:

github.com:
    user: dev-example
    oauth_token: {{ pass "github/dev-example" }}
    git_protocol: ssh

واسم الملف في المصدر private_dot_config/gh/private_hosts.yml.tmpl، فيخرج بصلاحيات 600. وعرضنا الناتج بالأمر chezmoi cat الذي يحسب الملف دون أن يكتبه، مع إخفاء التوكن في المقال:

github.com:
    user: dev-example
    oauth_token: gho_********************************uago
    git_protocol: ssh

وفي أول محاولة فشل الأمر برسالة Error: github/dev-example is not in the password store، والسبب أن مفتاح GPG الذي أنشأناه بالأمر --quick-gen-key مع النوع ed25519 كان للتوقيع فقط، فرفض pass التشفير به برسالة Unusable public key ولم يحفظ السر. وعندما أعدنا إنشاءه بالنوع default ظهر مفتاح فرعي للتشفير من نوع cv25519 [E] ونجح كل شيء. والقاعدة أن تقرأ رسالة الخطأ الأولى في السلسلة، لا الأخيرة.

ونقطة الضعف في هذه الطريقة أنها تحتاج مدير كلمات المرور مثبتاً ومفتوحاً على الجهاز قبل التطبيق، ولذلك وضعنا شرط lookPath في .chezmoiignore، فالجهاز الذي ليس فيه pass يحصل على كل شيء ما عدا هذا الملف.

الطريقة الثانية: ملف مشفر بأداة age داخل المستودع

الطريقة الثانية أن يدخل السر المستودع ولكن مشفراً، فلا يقرؤه إلا من يملك المفتاح. وأداة age صممها Filippo Valsorda كبديل بسيط لـ GPG في تشفير الملفات، وchezmoi يحملها في داخله فلا تحتاج تثبيتها، كما يشرح دليل التشفير مع age. فأنشأنا مفتاحاً، ووضعنا مفتاحه العام في .chezmoi.toml.tmpl كما رأيت فوق، ثم أضفنا .npmrc مشفراً:

$ chezmoi age-keygen --output /home/dev/.config/chezmoi/key.txt
$ grep 'public key' /home/dev/.config/chezmoi/key.txt
# public key: age12f53e8lkt6yk0sthx3s8kqgnymusa0lazkawyr40jfklcq20js3qxz0a7x
$ chezmoi add --encrypt /home/dev/.npmrc
$ head -c 120 /home/dev/.local/share/chezmoi/encrypted_private_dot_npmrc.age
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBEemI0ZWdid1J0Wjk0Tmt6
c0hsQTJzQXVGenJMYitu

والملف في المصدر الآن نص مشفر لا يقرؤه أحد، والأمر chezmoi cat ~/.npmrc يفك تشفيره عند الحاجة، وأظهر لنا السطر الأصلي //registry.npmjs.org/:_authToken=npm_.... وبعد أن أضفنا كل شيء شغلنا gitleaks على مستودع chezmoi كله للتأكد:

INF 1 commits scanned.
INF scanned ~3875 bytes (3.88 KB) in 235ms
INF no leaks found

لا الملف المشفر ولا قالب pass فيهما ما يكشف شيئاً. ولكن لاحظ أين انتقلت المشكلة: المفتاح الخاص key.txt صار هو السر الوحيد، ويجب أن يصل إلى كل جهاز جديد بطريقة آمنة، من مدير كلمات المرور أو عبر SSH، ولا يدخل المستودع أبداً، وسوف نرى بعد قليل ماذا يحدث عندما ننساه. وإذا كانت الأسرار لفريق كامل وليست لشخص واحد، فالأداة الأنسب SOPS مع مفاتيح age لكل عضو، وقد شرحناها في مقال تشفير الأسرار داخل Git مع SOPS.

والطريقة الثالثة هي أبسطها وتعمل مع كل الأدوات: الملف المحلي ~/.bashrc.local الذي رأيناه في بداية المقال، تضع فيه ما يخص الجهاز وحده، ولا ينتقل إلى أي مكان.

جهاز جديد بأمر واحد Bootstrap

الآن الاختبار الحقيقي: Container جديد من debian:trixie-slim، والهدف أن يصبح مثل حاسوبنا بأمر واحد. والأمر الرسمي في صفحة التثبيت ينزل chezmoi ويجلب المستودع ويطبقه، وأضفنا قبله تثبيت curl وGit لأن الـ Image الصغيرة لا تحتويهما، وأجبنا على الأسئلة في سطر الأمر، وجعلنا الجهاز «جهاز عمل» هذه المرة:

apt-get update -qq && apt-get install -y -qq --no-install-recommends curl ca-certificates git >/dev/null 2>&1
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b /usr/local/bin init --apply \
  --promptString "Git [email protected]" --promptBool "Is this a work machine=true" \
  git://git/chezmoi-dotfiles.git
info found chezmoi version 2.74.1 for latest/linux/amd64
info installed /usr/local/bin/chezmoi
Cloning into '/root/.local/share/chezmoi'...
packages installed on Debian GNU/Linux 13 (trixie): tmux less vi
chezmoi: .npmrc: open /root/.config/chezmoi/key.txt: no such file or directory
chezmoi: exit status 1
exit 1 after 34 s
-rw-r--r-- 1 root root  392 Nov 16 11:20 .bashrc
drwx------ 4 root root 4096 Nov 16 11:20 .config
-rw-r--r-- 1 root root  245 Nov 16 11:20 .gitconfig
-rw-r--r-- 1 root root  132 Jul 17 17:05 .profile

وهذا المخرج فيه أربعة أشياء تستحق الوقوف:

  • سكربت run_once وجد أن tmux وless وvi كلها ناقصة فثبتها بالمستخدم root دون sudo، كما صممناه.
  • ثم فشل عند .npmrc لأن المفتاح key.txt غير موجود على هذا الجهاز، وهذا بالضبط ما قلناه في قسم age: المفتاح لا يصل وحده.
  • الملفات تكتب بالترتيب، فكتب .bashrc و.gitconfig قبل الفشل، ولم يصل إلى .tmux.conf لأنه بعد .npmrc. أي أن الجهاز بقي في حالة نصف مطبقة حتى نصلح السبب.
  • الملف .bashrc صار 392 بايت، أي ملفنا، وملف Debian الذي كان مكانه ذهب دون سؤال، لأن init --apply لا يتوقف ليعرض الفرق. وعلى جهاز جديد هذا ما تريده، أما على جهاز فيه إعداد قديم فاستخدم chezmoi init ثم chezmoi diff ثم apply كخطوات منفصلة.

ثم نقلنا المفتاح إلى الجهاز الجديد، وفي الحياة الحقيقية يأتي من مدير كلمات المرور أو بالأمر scp من جهاز تثق به، وأعدنا التطبيق:

$ chmod 600 /root/.config/chezmoi/key.txt
$ chezmoi apply -v
diff --git a/.npmrc b/.npmrc
diff --git a/.tmux.conf b/.tmux.conf
exit 0 after 4 s
-rw------- 1 root root   74 Nov 16 11:20 /root/.npmrc
-rw-r--r-- 1 root root 1013 Nov 16 11:21 /root/.tmux.conf
ls: cannot access '/root/.config/gh/hosts.yml': No such file or directory
$ cat /root/.gitconfig
[user]
	name = Dev Example
	email = [email protected]
...
[credential]
	helper = cache --timeout=3600
[http]
	proxy = http://proxy.corp.example:3128
...
$ chezmoi apply -v
second apply exit 0
tmux 3.5a

في المخرج أعلاه لاحظ التالي:

  • أكمل التطبيق في 4 ثوان ما بقي فقط: .npmrc بصلاحيات 600 من البادئة private_، و.tmux.conf.
  • hosts.yml غير موجود، وهذا صحيح لأن pass غير مثبت على الجهاز الجديد، فتجاهله .chezmoiignore بدلاً من أن يفشل.
  • في .gitconfig ظهر قسم [http] بالبروكسي، لأننا أجبنا أن هذا جهاز عمل، ولم يظهر على الحاسوب القديم.
  • التطبيق الثاني لم يطبع شيئاً، فلا يوجد ما يتغير، ولم يعد تشغيل سكربت الحزم لأنه نجح مرة.
خط سير الأمر الواحد على Container جديد: تثبيت curl وgit، ثم تنزيل chezmoi من get.chezmoi.io، ثم clone للمستودع، ثم الأسئلة email وwork عبر --promptString، ثم سكربت run_once يثبت tmux وless وvi، ثم الملفات بالترتيب، وتحته المحاولة الأولى انتهت بـ exit 1 بعد 34 ثانية عند .npmrc لغياب key.txt، وبعد نقل مفتاح age انتهى التطبيق بـ exit 0 في 4 ثوان
أول تشغيل توقف عند السر، والثاني أكمل في 4 ثوان

وبعد ذلك يصبح العمل اليومي بسيطاً. عدلنا history-limit في .tmux.conf على الحاسوب القديم، فأظهر chezmoi status الملف كمعدل، فأخذنا التعديل إلى المصدر بالأمر chezmoi re-add ودفعناه. وهنا مشكلة صغيرة: chezmoi git -- push رفض بالرسالة The current branch main has no upstream branch، لأن المستودع أنشئ محلياً ثم أضيف له Remote، والحل push -u origin main مرة واحدة. وعلى الجهاز الجديد أمر واحد يجلب ويطبق:

$ chezmoi update -v
From git://git/chezmoi-dotfiles
   4547b44..28ab43f  main       -> origin/main
diff --git a/.tmux.conf b/.tmux.conf
-set -g history-limit 50000           # lines kept per pane (default 2000)
+set -g history-limit 100000          # lines kept per pane (default 2000)

ونفس الأمر الواحد تستطيع أن تجعله يعمل وحده في بيئات التطوير السحابية، فـ GitHub Codespaces يطبق مستودع Dotfiles تختاره في إعداداتك على كل Codespace جديد كما يشرح توثيق GitHub، وكذلك Dev Containers في VS Code، فيكفي أن يكون في المستودع سكربت تثبيت يعرف كيف يعمل دون أسئلة، وهذا سبب آخر لأن تجعل الإجابات في سطر الأمر أو بقيم افتراضية.

نفس المستودع على Linux وmacOS وWSL وWindows

جربنا نفس مصدر chezmoi على Windows 11 في هذا الجهاز، دون تثبيت ودون صلاحيات المسؤول: نزلنا chezmoi.exe الرسمي إلى مجلد تجربة، وشغلناه مع الخيارات --source و--destination و--config حتى لا يلمس المنزل الحقيقي، واستثنينا الملفات المشفرة بالخيار --exclude encrypted لأننا لم ننقل المفتاح:

PS> chezmoi execute-template '{{ .chezmoi.os }}/{{ .chezmoi.arch }} home={{ .chezmoi.homeDir }} pass=[{{ lookPath \"pass\" }}] git=[{{ lookPath \"git\" }}]'
windows/amd64 home=C:/Users/wajdy pass=[] git=[C:\Program Files\Git\cmd\git.exe]
PS> chezmoi apply --exclude encrypted -v   (then the files in the test home)
.bashrc
.gitconfig
.tmux.conf
Documents\PowerShell\Microsoft.PowerShell_profile.ps1
PS> Get-Content home\.gitconfig
...
[core]
	autocrlf = true
[credential]
	helper = manager
...

في المخرج أعلاه لاحظ التالي:

  • lookPath "pass" رجع فارغاً لأن pass غير موجود على Windows، فلم ينشأ hosts.yml، وlookPath "git" وجد Git for Windows.
  • ملف PowerShell تحت Documents أنشئ هنا فقط، لأن .chezmoiignore يتجاهله على غير Windows. وإذا كان مجلد Documents عندك منقولاً إلى OneDrive فالمسار الحقيقي مختلف، فتحقق منه بالمتغير $PROFILE كما يشرح توثيق ملفات PowerShell.
  • نفس قالب .gitconfig أخرج هنا فرع Windows: autocrlf = true وhelper = manager.
  • وأول محاولة لتنفيذ القالب فشلت برسالة wrong number of args for pass، لأن Windows PowerShell 5.1 يحذف علامات التنصيص الداخلية عند تمرير النص إلى برنامج خارجي، والحل كتابتها بالشكل \"pass\" كما في الأمر فوق.

ولماذا لم نجرب Stow على Windows؟ لأن الروابط نفسها هي المشكلة هناك، وهذا ما ظهر لنا عندما حاولنا إنشاء رابط واحد بحساب عادي:

PS> New-Item -ItemType SymbolicLink -Path home\link-test -Target home\.bashrc
Administrator privilege required for this operation.
PS> git config --system --get core.symlinks
false

فإنشاء رابط رمزي على Windows يحتاج صلاحية المسؤول أو تفعيل وضع المطور Developer Mode كما يشرح توثيق Microsoft، وGit for Windows يأتي بالإعداد core.symlinks=false فيحول أي رابط في المستودع إلى ملف نصي صغير فيه المسار، كما تشرح صفحة الروابط في ويكي Git for Windows. ولذلك أي طريقة تعتمد على الروابط تحتاج على Windows حلاً خاصاً، وchezmoi والمستودع العاري يكتبان ملفات حقيقية فلا يحتاجان شيئاً.

وأما بقية الأنظمة فالفروق معروفة وتعالج بنفس الشروط:

  • macOS: قيمة .chezmoi.os هي darwin، والـ Shell الافتراضية Zsh لا Bash، ومدير الحزم Homebrew، ومخزن كلمات المرور هو osxkeychain كما في قالبنا.
  • WSL: هو Linux كامل بمنزل خاص به، منفصل عن منزل Windows، فتطبق المستودع مرتين: مرة داخل WSL كأي Linux، ومرة في Windows إذا كنت تستخدم PowerShell أيضاً. وقد شرحنا كيف يعيش النظامان معاً في مقال WSL2 للمطورين.
  • نهايات الأسطر: سكربت Shell بنهايات Windows CRLF يفشل في Linux برسائل غريبة، فأضف إلى المستودع ملف .gitattributes فيه *.sh text eol=lf كما يشرح توثيق gitattributes.
جدول للأنظمة الأربعة: Linux بمنزل /home/dev وروابط تعمل ومدير حزم apt أو dnf، وmacOS بمنزل /Users/dev وHomebrew وZsh وosxkeychain، وWSL بمنزل Linux منفصل عن Windows، وWindows بمنزل C:/Users/wajdy وملف PowerShell وروابط تحتاج صلاحية المسؤول دون وضع المطور، وتحته ما جربناه على Windows 11 وسبب فشل الروابط مع core.symlinks false
الفروق في المسارات والروابط، لا في محتوى الإعداد

أي طريقة تختار؟

بعد التجارب كلها، الاختيار يعتمد على أربعة أسئلة: كم جهازاً لديك، وهل تختلف، وهل في إعدادك أسرار، وهل بينها Windows. ولكل طريقة نقاط قوة ونقاط ضعف:

  • سكربت الروابط: نقاط القوة أنه لا يحتاج إلا Git، وتفهم كل سطر فيه. ونقاط الضعف أن ln -sf مسح ملف Debian دون نسخة، ولا قوالب ولا أسرار، ولا يعمل على Windows دون صلاحيات.
  • GNU Stow: نقاط القوة أنه آمن افتراضياً ويرفض الكتابة فوق ملف حقيقي، وبنية الحزم واضحة، والتعديل في المنزل هو التعديل في المستودع. ونقاط الضعف أن --adopt يقلب الاتجاه بصمت، ولا يوجد ملف مختلف لكل جهاز إلا بحزم منفصلة، ويعتمد على الروابط.
  • المستودع العاري: نقاط القوة أنه Git فقط، وبلا روابط. ونقاط الضعف أن أمر add . واحداً يضيف المنزل كله، ولا قوالب ولا أسرار.
  • chezmoi: نقاط القوة القوالب لكل جهاز، والأسرار من مدير كلمات المرور أو مشفرة بـ age، وسكربتات التثبيت، والعمل على Windows، وdiff قبل كل تطبيق. ونقاط الضعف أنك تتعلم أداة جديدة بأسماء ملفات خاصة، وأن الملف في المنزل نسخة، فإذا عدلته مباشرة يجب أن تتذكر re-add أو chezmoi edit، وأن خطأ في سكربت أو سر ناقص يوقف التطبيق في منتصفه.
جدول قرار يقارن أربع طرق: git مع ln -s يحتاج Git وسكربتاً ولا يدعم أجهزة مختلفة ولا أسرار ولا روابط Windows ويناسب جهازاً أو اثنين، وGNU Stow يدعم الاختلاف بحزم منفصلة ويناسب عدة أجهزة Linux وmacOS، والمستودع العاري يحتاج Git فقط ويعمل دون روابط، وchezmoi ملف تنفيذي واحد بقوالب وage ومديري كلمات المرور ويعمل على Windows
كلما زادت الأجهزة واختلفت، زادت حاجتك إلى القوالب

وتوصيتنا العملية: إذا كان لديك جهاز أو جهازان Linux متشابهان فابدأ بـ Stow وسكربت install.sh كالذي كتبناه، فهو أبسط ما يعمل بأمان. وإذا كان لديك حاسوب عمل وحاسوب شخصي، أو بينها Windows، أو في إعدادك توكنات، فاذهب إلى chezmoi مباشرة، فالانتقال إليه لاحقاً أصعب من البدء به. وفي الحالتين ضع gitleaks قبل كل Commit. وإذا أردت مقارنة أوسع مع أدوات أخرى مثل yadm وrcm وHome Manager فالمشروع نفسه ينشر جدول مقارنة، مع ملاحظة أنه مكتوب من وجهة نظر chezmoi.

أخطاء شائعة

  • نسخ مجلد كامل من ~/.config إلى المستودع دون النظر في كل ملف فيه، كما فعلنا مع gh.
  • مستودع إعداد عام دون أي فحص للأسرار، ثم الاعتماد على حذف الملف لاحقاً: الحذف لا يمسح التاريخ، والتوكن يجب إلغاؤه.
  • وضع المفتاح الخاص key.txt أو مفاتيح ~/.ssh/id_* في المستودع نفسه.
  • ln -sf في سكربت التثبيت دون نسخة احتياطية، أو stow --adopt دون قراءة git diff بعده.
  • git add . في المستودع العاري، فيدخل المنزل كله.
  • ملفات بصلاحية التنفيذ لأنها جاءت من Windows، فتنتقل الصلاحية الخاطئة إلى كل جهاز.
  • سكربت تثبيت يسأل أسئلة أو يحتاج sudo، فيفشل في Codespaces والـ Containers حيث لا يوجد من يجيب.
  • chezmoi init --apply على جهاز فيه إعداد قديم مهم دون diff قبله.
  • تعديل الملف في المنزل مع chezmoi ونسيان re-add، فيمسحه أول update أو يتوقف عنده.
  • الاعتماد على الروابط في مستودع يستخدم على Windows.

قائمة تحقق Checklist

  • المستودع فيه الإعداد فقط: لا تاريخ أوامر، ولا Cache، ولا مفاتيح خاصة، ولا توكنات بنص واضح.
  • كل ما يخص جهازاً واحداً في ملف محلي مثل ~/.bashrc.local خارج Git.
  • gitleaks في خطاف pre-commit، ومرة على التاريخ كله قبل أن تجعل المستودع عاماً.
  • سكربت التثبيت يأخذ نسخة احتياطية من أي ملف يستبدله، ولا يسأل أي سؤال، ويعمل بالمستخدم root ودونه.
  • الأسرار من مدير كلمات المرور أو مشفرة بـ age، والمفتاح الخاص له طريق آمن إلى الأجهزة الجديدة ونسخة احتياطية.
  • صلاحيات الملفات صحيحة في Git: 644 للإعداد و755 للسكربتات فقط.
  • .gitattributes يجبر نهايات LF على السكربتات إذا كان Windows أحد أجهزتك.
  • جربت الأمر الواحد على Container جديد فعلاً، لا على جهازك الذي فيه كل شيء أصلاً.

حذف المختبر Cleanup

docker rm -f lnxf-laptop lnxf-git lnxf-fresh2
docker volume rm lnxf-dot-repos
docker network rm lnxf-dot
docker rmi lnxf-dot-laptop:1 lnxf-dot-git:1

الخلاصة

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • ملفات الإعداد كود، ومكانها مستودع Git واحد تطبقه على أي جهاز، مع فصل ما يخص الجهاز في ملف محلي.
  • ln -sf مسح ملف Debian دون أن يخبرنا، وStow رفض الكتابة فوقه وألغى العملية كلها، و--adopt نقل ملف Debian فوق ملفنا في المستودع.
  • سكربت install.sh مع نسخة احتياطية جهز Container جديداً بـ Stow في 26 ثانية.
  • المستودع العاري لا يحتاج إلا Git، وأول إعداد فيه status.showUntrackedFiles no، وأخطر أمر فيه add ..
  • chezmoi أخرج .gitconfig مختلفاً على Linux وWindows وجهاز العمل من قالب واحد، و--promptString يأخذ نص السؤال لا اسم المفتاح.
  • gitleaks التقط توكن gho_ في التاريخ ثم منع الـ Commit كله بخطاف pre-commit، والتوكن صار يأتي من pass أو من ملف مشفر بـ age.
  • الأمر الواحد على Container جديد توقف بعد 34 ثانية لغياب مفتاح age، وأكمل في 4 ثوان بعد نقله.
  • على Windows يحتاج الرابط صلاحية المسؤول، فالطرق التي تكتب ملفات حقيقية هي التي تعمل هناك دون إعداد خاص.

وبهذا المقال تكتمل مرحلة الطرفية: برنامج الطرفية، والـ Shell، وسطر الأوامر، والأدوات الحديثة، والجلسات مع tmux، وكلها الآن في مستودع واحد ينتقل معك. وهذه مقالات مرتبطة:

دليلالجلسات Sessions مع tmux: عمل لا يضيع إذا انقطع SSHنقطع اتصال SSH في منتصف مهمة طويلة ونرى لماذا تتوقف دونه وتكمل داخل tmux، ثم نتعلم النوافذ والتقسيم ووضع النسخ ومشاركة الجلسة وما يفعله systemd-logind بجلستك.دليلالصدفة Shell: Bash أم Zsh أم Fish أم PowerShell؟نفس المهام في Bash وZsh وFish وPowerShell مع زمن البدء وترتيب ملفات الإعداد كما قسناه، حتى تعرف أي Shell يناسب السيرفر وأيها يناسب جهاز التطوير.دليلسطر الأوامر Prompt مع Starship وOh My Posh وOh My Zshاجعل سطر الأوامر يعرض فرع Git ورمز الخطأ ومدة الأمر وسياق Kubernetes، وقس كم يكلفك ذلك بعد كل Enter، من مشروع صغير إلى مستودع فيه 200 ألف ملف.دليلأدوات سطر الأوامر CLI الحديثة: fzf وripgrep وbat وzoxideقسنا ripgrep وfd وfzf وzoxide وbat وeza وdelta على مصدر نواة Linux كاملاً، لتعرف ما تضيفه كل أداة ومتى تبقى مع grep وfind.دليلإدارة النسخ مع Git للمبتدئين: لماذا نحتاجها وكيف تعمللماذا تضيع الملفات بأسماء final_v2 ويمسح الزملاء عمل بعضهم، وكيف يحل Git ذلك على مشروع حقيقي من أول commit.دليلSecrets Scanning: كيف تكتشف الأسرار المسربة في الكودكيف يخرج المفتاح من جهازك إلى تاريخ Git وخط CI، وكيف تكتشفه قبل غيرك، وماذا تفعل في الساعة الأولى بعد تسربه.دليلتشفير الأسرار داخل Git مع SOPS بمفاتيح ageنضع الأسرار في Git مشفرة بحيث يراجعها الفريق مع الكود دون أن يقرأها كل من يقرأ المستودع، ونرى ما يحدث عند التلاعب بالملف، وعند إخراج عضو من الفريق.دليلGit Hooks مع pre-commit: افحص الكود قبل أن يدخل المستودعكيف تمنع الأسرار وملفات الإعداد المعطوبة قبل أن تصل إلى مستودع الفريق، بخطافات على جهاز المطور مع إطار pre-commit، ثم بخطاف pre-receive على Gitea لا يستطيع أحد أن يتخطاه.دليلBitwarden أم Vaultwarden أم Passbolt؟ مدير كلمات مرور لفريقكمقارنة بين مديري كلمات المرور للفرق في طريقة المشاركة والترخيص والسعر والمزايا، ودليل يساعدك على اختيار الأنسب لشركتك.دليلWSL2 للمطورين: كيف يعمل Linux داخل Windowsما الذي يعمل تحت WSL 2 من آلة افتراضية ونواة Linux وشبكة ونظامي ملفات، ولماذا يبطئ مشروعك على قرص C مئة مرة، مع مختبر قسنا فيه الملفات وDocker والشبكة على Windows 11.دليلPowerShell للمسؤولين: الكائنات Objects بدل النصلماذا ينكسر السكربت الذي يقص مخرج الأوامر في Windows، وكيف تبني بكائنات PowerShell تقريراً صباحياً عن الأقراص والخدمات والأخطاء يعمل في 5.1 و7 دون صلاحيات المدير.

سجل التحديثات

  • 16 نوفمبر 2026: كتابة الدليل، وتنفيذ التجارب في Containers من Debian 13 مع Git 2.47.3 وGNU Stow 2.4.1 وchezmoi 2.74.1 وgitleaks 8.30.1 وage 1.2.1 وpass 1.7.4 وGnuPG 2.4.7، وتجربة chezmoi.exe 2.74.1 على Windows 11 مع Windows PowerShell 5.1، على Docker Engine 29.8.0.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.