نام (NAME)

git-for-each-ref - چاپ اطلاعات برای هر یک از مراجع

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

git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
                   [(--sort=<key>)...] [--format=<format>]
                   [--include-root-refs] [--points-at=<object>]
                   [--merged[=<object>]] [--no-merged[=<object>]]
                   [--contains[=<object>]] [--no-contains[=<object>]]
                   [(--exclude=<pattern>)...] [--start-after=<marker>]
                   [ --stdin | (<pattern>...)]

توضیحات (DESCRIPTION)

پیمایش روی تمامی مراجعی که با <pattern> مطابقت دارند و نمایش آن‌ها بر اساس <format> داده‌شده، پس از مرتب‌سازی آن‌ها بر اساس مجموعه <key> ارائه‌شده. اگر <count> داده شود، پس از نمایش آن تعداد مرجع متوقف می‌شود. مقادیر جای‌گذاری‌شده در <format> را می‌توان به‌صورت اختیاری به شکل رشته‌های متنی در زبان میزبان مشخص‌شده نقل‌قول (quote) کرد تا امکان ارزیابی مستقیم آن‌ها در آن زبان فراهم شود.

گزینه‌ها (OPTIONS)

<pattern>...

--stdin

--count=<count>

--sort=<key>

--format[=<format>]

در صورت عدم تعیین، <format> به‌طور پیش‌فرض به %(objectname) SPC %(objecttype) TAB %(refname) تنظیم می‌شود.

--color[=<when>]

--shell, --perl, --python, --tcl

--points-at=<object>

--merged[=<object>]

--no-merged[=<object>]

--contains[=<object>]

--no-contains[=<object>]

--ignore-case

--omit-empty

--exclude=<excluded-pattern>

--include-root-refs

--start-after=<marker>

نام‌های فیلد (FIELD NAMES)

مقادیر گوناگون برگرفته از فیلدهای ساختاریافته در اشیاء ارجاع‌شده می‌توانند برای جای‌گذاری در خروجی حاصل یا به عنوان کلیدهای مرتب‌سازی استفاده شوند.

برای تمامی اشیاء، نام‌های زیر قابل استفاده هستند:

refname

objecttype

objectsize

objectname

deltabase

upstream

push

HEAD

color

align

if

symref

signature

signature:grade

signature:signer

signature:key

signature:fingerprint

signature:primarykeyfingerprint

signature:trustlevel

worktreepath

ahead-behind:<commit-ish>

is-base:<commit-ish>

*--*--*--*--*--* refs/heads/A
\
 \
  *--*--*--* refs/heads/B
   \     \
    \     \
     *     * refs/heads/C
      \
       \
        *--* refs/heads/D

refs/heads/A:
refs/heads/B:(D)
refs/heads/C:

describe[:<option>,...]

علاوه بر موارد بالا، برای اشیاء کامیت و تگ، نام فیلدهای سربرگ (tree، parent، object، type و tag) را می‌توان برای تعیین مقدار موجود در فیلد سربرگ استفاده کرد. فیلدهای tree و parent را نیز می‌توان درست مانند objectname با اصلاح‌کننده‌های :short و :short=<length> استفاده کرد.

برای اشیاء کامیت و تگ، فیلدهای ویژه creatordate و creator بسته به نوع شیء، متناظر با تاریخ مناسب یا چندتایی نام-ایمیل-تاریخ برگرفته از فیلدهای committer یا tagger خواهند بود. این فیلدها برای کار با ترکیبی از تگ‌های حاشیه‌نویسی‌شده و سبک در نظر گرفته شده‌اند.

برای اشیاء تگ، اگر پیشوند ستاره (*) قبل از fieldname بیاید، به مقدار fieldname شیء پوسته‌گیری‌شده (peeled) گسترش می‌یابد، نه خود شیء تگ.

فیلدهایی که چندتایی نام-ایمیل-تاریخ را به عنوان مقدار خود دارند (author، committer و tagger) می‌توانند با پسوندهای name، email و date همراه شوند تا مؤلفه نام‌برده را استخراج کنند. برای فیلدهای ایمیل (authoremail، committeremail و taggeremail)، می‌توان :trim را اضافه کرد تا ایمیل بدون علامت‌های قلاب‌مانند (<>) به دست آید، و :localpart را برای دریافت بخش پیش از نماد @ از ایمیل پیراسته به کار برد. علاوه بر این‌ها، گزینه :mailmap و گزینه‌های متناظر :mailmap,trim و :mailmap,localpart را می‌توان (ترتیب اهمیتی ندارد) برای دریافت مقادیر نام و ایمیل مطابق با فایل .mailmap یا مطابق با فایل تعیین‌شده در متغیر پیکربندی mailmap.file یا mailmap.blob استفاده کرد (به gitmailmap(5) مراجعه کنید).

داده خام در یک شیء، raw است.

raw:size

توجه داشته باشید که --format=%(raw) را نمی‌توان همراه با گزینه‌های --python، --shell، --tcl استفاده کرد، زیرا چنین زبان‌هایی ممکن است داده‌های باینری دلخواه را در نوع متغیر رشته‌ای خود پشتیبانی نکنند.

پیام موجود در یک شیء کامیت یا تگ، contents است که از آن می‌توان contents:<part> را برای استخراج بخش‌های مختلف به کار برد:

contents:size

contents:subject

contents:body

contents:signature

contents:lines=<n>

علاوه بر این، تریلرها آن‌گونه که توسط git-interpret-trailers(1) تفسیر می‌شوند، به صورت trailers[:<option>,...] (یا با استفاده از نام مستعار قدیمی contents:trailers[:<option>,...]) به دست می‌آیند. برای مقادیر معتبر <option>، بخش trailers در git-log(1) را ببینید.

برای اهداف مرتب‌سازی، فیلدهای دارای مقادیر عددی بر اساس ترتیب عددی مرتب می‌شوند (objectsize، authordate، committerdate، creatordate، taggerdate). تمام فیلدهای دیگر بر اساس ترتیب مقدار بایتی خود مرتب می‌شوند.

همچنین گزینه‌ای برای مرتب‌سازی بر اساس نسخه‌ها وجود دارد که این کار را می‌توان با استفاده از نام فیلد version:refname یا نام مستعار آن v:refname انجام داد.

در هر صورت، نام فیلدی که به فیلدی غیرقابل اعمال بر شیء ارجاع‌شده توسط مرجع اشاره دارد، باعث بروز خطا نمی‌شود؛ بلکه به جای آن یک رشته خالی برمی‌گرداند.

به عنوان یک حالت خاص برای فیلدهای از نوع تاریخ، می‌توانید با افزودن : و به دنبال آن نام قالب تاریخ، قالبی را برای تاریخ مشخص کنید (مقدارهایی را که گزینه --date در git-rev-list(1) می‌پذیرد ببینید). اگر این قالب‌بندی در یک کلید --sort ارائه شود، مراجع به جای مقدار عددی برچسب زمانی زیربنایی، بر اساس مقدار بایتی رشته قالب‌بندی‌شده مرتب خواهند شد.

برخی اتم‌ها مانند %(align) و %(if) همیشه نیازمند یک %(end) منطبق هستند. ما به آن‌ها «اتم‌های آغازین» می‌گوییم و گاهی آن‌ها را با %($open) نشان می‌دهیم.

هنگامی که نقل‌قول ویژه یک زبان اسکریپت‌نویسی فعال است، تمام موارد میان یک اتم آغازین سطح بالا و %(end) منطبق بر آن، بر اساس معناشناسی اتم آغازین ارزیابی می‌شود و تنها نتیجه نهایی آن در سطح بالا نقل‌قول خواهد شد.

مثال‌ها (EXAMPLES)

نمونه‌ای که مستقیماً متنی قالب‌بندی‌شده تولید می‌کند. نمایش ۳ کامیت تگ‌شده اخیر:

#!/bin/sh
git for-each-ref --count=3 --sort='-*authordate' \
`--format='From: %(*authorname) %(*authoremail)
Subject: %(*subject)
Date: %(*authordate)
Ref: %(*refname)
%(*body)
' 'refs/tags'

یک مثال ساده که استفاده از eval در پوسته را روی خروجی نشان می‌دهد و کاربرد --shell را به نمایش می‌گذارد. فهرست کردن پیشوندهای تمامی headها:

#!/bin/sh
git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
while read entry
do
        eval "$entry"
        echo `dirname $ref`
done

گزارشی جامع‌تر درباره تگ‌ها، که نشان می‌دهد قالب می‌تواند یک اسکریپت کامل باشد:

#!/bin/sh
fmt='
        r=%(refname)
        t=%(*objecttype)
        T=${r#refs/tags/}
        o=%(*objectname)
        n=%(*authorname)
        e=%(*authoremail)
        s=%(*subject)
        d=%(*authordate)
        b=%(*body)
        kind=Tag
        if test "z$t" = z
        then
                # could be a lightweight tag
                t=%(objecttype)
                kind="Lightweight tag"
                o=%(objectname)
                n=%(authorname)
                e=%(authoremail)
                s=%(subject)
                d=%(authordate)
                b=%(body)
        fi
        echo "$kind $T points at a $t object $o"
        if test "z$t" = zcommit
        then
                echo "The commit was authored by $n $e
at $d, and titled
    $s
Its message reads as:
"
                echo "$b" | sed -e "s/^/    /"
                echo
        fi
'
eval=`git for-each-ref --shell --format="$fmt" \
        --sort='*objecttype' \
        --sort=-taggerdate \
        refs/tags`
eval "$eval"

نمونه‌ای برای نمایش کاربرد %(if)...%(then)...%(else)...%(end). این الگو پیش از نام شاخه جاری یک ستاره قرار می‌دهد.

git for-each-ref --format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)" refs/heads/

نمونه‌ای برای نمایش کاربرد %(if)...%(then)...%(end). در صورت وجود، نام نویسنده را چاپ می‌کند.

git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"

هشدارها (CAVEATS)

توجه داشته باشید که اندازه‌های اشیاء روی دیسک به طور دقیق گزارش می‌شوند، اما باید در نتیجه‌گیری درباره اینکه کدام مراجع یا اشیاء مسئول مصرف فضای دیسک هستند احتیاط کرد. اندازه یک شیء بسته‌بندی‌شده غیردلتا ممکن است بسیار بزرگتر از اندازه اشیایی باشد که با آن تفاضل دلتا دارند، اما اینکه کدام شیء به عنوان پایه و کدام یک به عنوان دلتا تعیین شود اختیاری بوده و در طول یک repack دستخوش تغییر می‌شود.

همچنین توجه داشته باشید که ممکن است چندین نسخه از یک شیء در پایگاه داده اشیاء وجود داشته باشد؛ در این حالت، مشخص نیست که اندازه یا پایه دلتای کدام نسخه گزارش خواهد شد.

نکات (NOTES)

هنگام ترکیب چندین فیلتر --contains و --no-contains، تنها مراجعی نمایش داده می‌شوند که حداقل شامل یکی از کامیت‌های --contains بوده و هیچ‌یک از کامیت‌های --no-contains را در بر نداشته باشند.

هنگام ترکیب چندین فیلتر --merged و --no-merged، تنها مراجعی نمایش داده می‌شوند که حداقل از یکی از کامیت‌های --merged قابل دسترسی بوده و از هیچ‌یک از کامیت‌های --no-merged قابل دسترسی نباشند.

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

git-show-ref(1)

گیت (GIT)

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