نام (NAME)

git-interpret-trailers - افزودن یا تجزیه اطلاعات ساختاریافته در انتهای پیام کامیت

خلاصه دستور (SYNOPSIS)

git interpret-trailers [--in-place] [--trim-empty]
                        [(--trailer (<key>|<key-alias>)[(=|:)<value>])...]
                        [--parse] [<file>...]

توضیحات (DESCRIPTION)

افزودن یا تجزیه خطوط دنباله (trailer) که ساختاری مشابه با سرآیندهای ایمیل در RFC 822 دارند، در انتهای بخش آزاد پیام کامیت. برای نمونه، در پیام کامیت زیر:

subject
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>

دو خط پایانی که با Signed-off-by آغاز می‌شوند، دنباله (trailer) هستند.

این دستور پیام‌های کامیت را از آرگومان‌های <file> یا در صورت عدم تعیین <file>، از ورودی استاندارد می‌خواند. اگر --parse مشخص شود، خروجی شامل دنباله‌های تجزیه‌شده از ورودی خواهد بود، بدون آنکه گزینه‌های خط فرمان یا متغیرهای پیکربندی بر آن‌ها تاثیری بگذارند.

در غیر این صورت، این دستور متغیرهای پیکربندی trailer.<key-alias> (که می‌توانند دنباله‌های جدید اضافه کرده یا جایگاه آن‌ها را تغییر دهند) و همچنین آرگومان‌های خط فرمان را که می‌توانند متغیرهای پیکربندی را بازنویسی کنند (مانند --trailer=... که آن هم می‌تواند دنباله‌های جدید بیفزاید)، روی هر فایل ورودی اعمال می‌کند. نتیجه در خروجی استاندارد منتشر می‌شود.

این دستور همچنین می‌تواند بر روی خروجی git-format-patch(1) عمل کند، که ساختاری غنی‌تر از یک پیام کامیت ساده دارد. مشخصاً چنین خروجی‌ای شامل یک پیام کامیت (همانند بالا)، یک خط جداکننده --- و یک بخش وصله (patch) است. برای این ورودی‌ها، بخش جداکننده و وصله توسط این دستور تغییر نمی‌کنند و همان‌گونه که هستند در خروجی منتشر می‌شوند، مگر اینکه --no-divider تعیین شده باشد.

برخی متغیرهای پیکربندی نحوه اعمال آرگومان‌های --trailer روی هر ورودی و نحوه تغییر هر دنباله موجود در ورودی را کنترل می‌کنند. این متغیرها همچنین افزودن خودکار برخی دنباله‌ها را امکان‌پذیر می‌سازند.

به‌طور پیش‌فرض، یک آرگومان <key>=<value> یا <key>:<value> که با استفاده از --trailer داده می‌شود، تنها در صورتی پس از دنباله‌های موجود الحاق خواهد شد که آخرین دنباله دارای جفت (<key>, <value>) متفاوتی باشد (یا اگر هیچ دنباله‌ای از قبل وجود نداشته باشد). بخش‌های <key> و <value> برای حذف فاصله‌های خالی ابتدا و انتها پیراسته (trim) می‌شوند و مقادیر پیراسته‌شده حاصل در خروجی به این صورت نمایش داده خواهند شد:

key: value

این بدان معنی است که <key> و <value> پیراسته با ": " (یک دو‌نقطه و به دنبال آن یک فاصله) از یکدیگر جدا می‌شوند.

برای راحتی، می‌توان یک <key-alias> (نام مستعار کلید) را پیکربندی کرد تا تایپ گزینه --trailer در خط فرمان کوتاه‌تر شود. این کار را می‌توان با متغیر پیکربندی trailer.<key-alias>.key انجام داد. مقدار <key-alias> باید یک پیشوند از رشته کامل <key> باشد، هرچند بزرگی و کوچکی حروف اهمیتی ندارد. برای نمونه، اگر در پیکربندی خود مقدار زیر را داشته باشید:

trailer.sign.key "Signed-off-by: "

کافی است در خط فرمان عبارت --trailer="sign: foo" را به جای --trailer="Signed-off-by: foo" مشخص کنید.

به‌طور پیش‌فرض دنباله جدید در انتهای تمام دنباله‌های موجود قرار می‌گیرد. اگر دنباله‌ای از قبل وجود نداشته باشد، دنباله جدید در انتهای ورودی ظاهر می‌شود. اگر از قبل خط خالی وجود نداشته باشد، یک خط خالی پیش از دنباله جدید اضافه خواهد شد.

دنباله‌های موجود با جستجوی گروهی از یک یا چند خط در ورودی استخراج می‌شوند که یا (i) تماماً دنباله باشند، یا (ii) شامل دست‌کم یک دنباله تولیدشده توسط گیت یا پیکربندی‌شده توسط کاربر بوده و حداقل ۲۵٪ آن از دنباله‌ها تشکیل شده باشد. پیش از این گروه باید یک یا چند خط خالی (یا فقط حاوی فاصله‌های سفید) وجود داشته باشد. این گروه یا باید در انتهای ورودی باشد یا آخرین خطوط غیرخالی پیش از خطی باشد که با --- شروع می‌شود (به همراه یک فاصله یا پایان خط).

هنگام خواندن دنباله‌ها، نمی‌تواند هیچ فاصله خالی قبل یا درون <key> وجود داشته باشد، اما هر تعداد کاراکتر فاصله معمولی و تب (tab) میان <key> و جداکننده مجاز است. قبل، درون یا بعد از <value> می‌تواند فضای خالی وجود داشته باشد. مقدار <value> ممکن است در چند خط امتداد یابد به‌طوری‌که هر خط بعدی با حداقل یک فاصله سفید آغاز شود، مشابه سازوکار "تازدن" (folding) در سرآیندهای RFC 822. مثال:

key: This is a very long value, with spaces and
  newlines in it.

توجه داشته باشید که دنباله‌ها از بسیاری از قوانین سرآیندهای RFC 822 پیروی نمی‌کنند (و هدف آن نیز پیروی از آن‌ها نیست). برای نمونه، از قاعده کدگذاری (encoding) پیروی نمی‌کنند.

گزینه‌ها (OPTIONS)

--in-place, --no-in-place

--trim-empty, --no-trim-empty

--trailer=<key>[(=|:)<value>], --no-trailer

--where=<placement>, --no-where

--if-exists=<action>, --no-if-exists

--if-missing=<action>, --no-if-missing

--only-trailers, --no-only-trailers

--only-input, --no-only-input

--unfold, --no-unfold

--parse

--divider, --no-divider

پیکربندی (CONFIGURATION)

تمامی موارد زیر در این بخش به طور گزینش‌شده از مستندات git-config(1) درج شده‌اند. محتوا با آنچه در آنجا موجود است یکسان است:

trailer.separators

trailer.where

trailer.ifexists

trailer.ifmissing

trailer.<key-alias>.key

trailer.<key-alias>.where

trailer.<key-alias>.ifexists

trailer.<key-alias>.ifmissing

trailer.<key-alias>.command

trailer.<key-alias>.cmd

مثال‌ها (EXAMPLES)

$ git config trailer.sign.key "Signed-off-by"
$ cat msg.txt
subject
body text
$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
subject
body text
Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>

$ cat msg.txt
subject
body text
Signed-off-by: Bob <bob@example.com>
$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt
$ cat msg.txt
subject
body text
Signed-off-by: Bob <bob@example.com>
Acked-by: Alice <alice@example.com>

$ git format-patch -1
0001-foo.patch
$ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch

$ cat msg1.txt
subject
body text
$ git config trailer.sign.key "Signed-off-by: "
$ git config trailer.sign.ifmissing add
$ git config trailer.sign.ifexists doNothing
$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
$ git interpret-trailers --trailer sign <msg1.txt
subject
body text
Signed-off-by: Bob <bob@example.com>
$ cat msg2.txt
subject
body text
Signed-off-by: Alice <alice@example.com>
$ git interpret-trailers --trailer sign <msg2.txt
subject
body text
Signed-off-by: Alice <alice@example.com>

$ git config trailer.separators ":#"
$ git config trailer.fix.key "Fix #"
$ echo "subject" | git interpret-trailers --trailer fix=42
subject
Fix #42

$ cat ~/bin/glog-find-author
#!/bin/sh
test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
$ cat msg.txt
subject
body text
$ git config trailer.help.key "Helped-by: "
$ git config trailer.help.ifExists "addIfDifferentNeighbor"
$ git config trailer.help.cmd "~/bin/glog-find-author"
$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
subject
body text
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Christian Couder <christian.couder@gmail.com>

$ cat ~/bin/glog-grep
#!/bin/sh
test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
$ cat msg.txt
subject
body text
$ git config trailer.ref.key "Reference-to: "
$ git config trailer.ref.ifExists "replace"
$ git config trailer.ref.cmd "~/bin/glog-grep"
$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
subject
body text
Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)

$ cat msg.txt
subject
body text
see: HEAD~2
$ cat ~/bin/glog-ref
#!/bin/sh
git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
$ git config trailer.see.key "See-also: "
$ git config trailer.see.ifExists "replace"
$ git config trailer.see.ifMissing "doNothing"
$ git config trailer.see.cmd "glog-ref"
$ git interpret-trailers --trailer=see <msg.txt
subject
body text
See-also: fe3187489d69c4 (subject of related commit)

$ cat temp.txt
***subject***
***message***
Fixes: Z
Cc: Z
Reviewed-by: Z
Signed-off-by: Z
$ sed -e 's/ Z$/ /' temp.txt > commit_template.txt
$ git config commit.template commit_template.txt
$ cat .git/hooks/commit-msg
#!/bin/sh
git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
mv "\$1.new" "\$1"
$ chmod +x .git/hooks/commit-msg

همچنین ببینید (SEE ALSO)

git-commit(1), git-format-patch(1), git-config(1)

گیت (GIT)

بخشی از مجموعه git(1)