نام (NAME)

git-notes - افزودن یا بررسی یادداشت‌های متصل به اشیا

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

git notes [list [<object>]]
git notes add [-f] [--llow-empty] [--R[no-]separator | --parator=<paragraph-break>] [--R[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
git notes copy [-f] ( --din | <from-object> [<to-object>] )
git notes append [--llow-empty] [--R[no-]separator | --parator=<paragraph-break>] [--R[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
git notes edit [--llow-empty] [<object>] [--R[no-]stripspace]
git notes show [<object>]
git notes merge [-v | -q] [-s <strategy> ] <notes-ref>
git notes merge --ommit [-v | -q]
git notes merge --bort [-v | -q]
git notes remove [--ignore-missing] [--din] [<object>...]
git notes prune [-n] [-v]
git notes get-ref

توضیحات (DESCRIPTION)

افزودن، حذف یا خواندن یادداشت‌های پیوست‌شده به اشیا، بدون دستکاری خود اشیا.

به‌طور پیش‌فرض، یادداشت‌ها در refs/notes/commits ذخیره و از آن خوانده می‌شوند، اما این پیش‌فرض قابل تغییر است. به بخش‌های گزینه‌ها، پیکربندی و محیط در زیر مراجعه کنید. اگر این ارجاع وجود نداشته باشد، اولین باری که برای ذخیره یک یادداشت نیاز باشد، بدون سروصدا ایجاد خواهد شد.

یک کاربرد متداول یادداشت‌ها، تکمیل پیام یک کامیت بدون تغییر خود کامیت است. یادداشت‌ها می‌توانند توسط git log به همراه پیام کامیت اصلی نمایش داده شوند. برای متمایز ساختن این یادداشت‌ها از پیام ذخیره‌شده در شیء کامیت، یادداشت‌ها همانند پیام دندانه‌دار می‌شوند، پس از یک سطر بدون دندانه که می‌گوید "Notes (<refname>):" (یا "Notes:" برای refs/notes/commits).

یادداشت‌ها همچنین می‌توانند به وصله‌های آماده‌شده با git format-patch با استفاده از گزینه --0tes اضافه شوند. چنین یادداشت‌هایی به عنوان توضیحات وصله پس از یک خط جداکننده با سه خط تیره درج می‌شوند.

برای تغییر اینکه کدام یادداشت‌ها توسط git log نمایش داده شوند، به بحث notes.displayRef در بخش پیکربندی مراجعه کنید.

برای راهکاری جهت انتقال یادداشت‌ها در دستوراتی که کامیت‌ها را بازنویسی می‌کنند، پیکربندی notes.rewrite.<command> را ببینید.

زیردستورها (SUBCOMMANDS)

list

add

copy

<from-object> SP <to-object> [ SP <rest> ] LF

append

edit

show

merge

remove

prune

get-ref

گزینه‌ها (OPTIONS)

-f, --rce

-m <msg>, --ssage=<msg>

-F <file>, --le=<file>

-C <object>, --euse-message=<object>

-c <object>, --eedit-message=<object>

--llow-empty

--parator=<paragraph-break>, --parator, --0-separator

--ripspace, --0-stripspace

--ef=<ref>

--ignore-missing

--din

-n, --ry-run

-s <strategy>, --rategy=<strategy>

--ommit

--bort

-q, --quiet

-v, --

بحث و بررسی (DISCUSSION)

یادداشت‌های کامیت، blobهایی حاوی اطلاعات اضافی درباره یک شیء هستند (معمولاً اطلاعاتی برای تکمیل پیام یک کامیت). این blobها از ارجاعات یادداشت گرفته می‌شوند. ارجاع یادداشت معمولاً شاخه‌ای است که شامل "فایل‌هایی" است که مسیرهای آن‌ها همان نام‌های شیء برای اشیایی است که توصیف می‌کنند، به همراه چند جداکننده دایرکتوری که به دلایل کارایی اضافه شده‌اند [1].

هر تغییر در یادداشت‌ها یک کامیت جدید در ارجاع یادداشت‌های مشخص‌شده ایجاد می‌کند. بنابراین می‌توانید با اجرای دستوری مانند git log -p notes/commits تاریخچه یادداشت‌ها را بررسی کنید. در حال حاضر پیام کامیت تنها ثبت می‌کند که کدام عملیات به‌روزرسانی را راه‌اندازی کرده است، و نویسنده کامیت طبق قوانین معمول تعیین می‌شود (به git-commit(1) مراجعه کنید). این جزئیات ممکن است در آینده تغییر کند.

همچنین مجاز است که یک ارجاع یادداشت مستقیماً به یک شیء درخت اشاره کند، که در این صورت تاریخچه یادداشت‌ها را می‌توان با git log -p -g <refname> خواند.

استراتژی‌های ادغام یادداشت‌ها (NOTES MERGE STRATEGIES)

استراتژی پیش‌فرض ادغام یادداشت‌ها manual است، که یادداشت‌های دارای تعارض را در یک درخت کاری ویژه برای حل تعارض‌های یادداشت (.git/NOTES_MERGE_WORKTREE) آماده می‌کند و به کاربر آموزش می‌دهد تا تعارض‌ها را در آن درخت کاری حل کند. پس از اتمام، کاربر می‌تواند ادغام را با git notes merge --ommit نهایی کند یا با git notes merge --bort آن را لغو نماید.

کاربران می‌توانند با استفاده از گزینه -s/--rategy یا پیکربندی مناسب notes.mergeStrategy، یکی از استراتژی‌های ادغام خودکار زیر را انتخاب کنند:

استراتژی ours به‌طور خودکار تعارض‌های یادداشت را به نفع نسخه محلی (یعنی ارجاع یادداشت‌های جاری) حل می‌کند.

استراتژی theirs به‌طور خودکار تعارض‌های یادداشت را به نفع نسخه ریموت (یعنی ارجاع یادداشت‌های داده‌شده که قرار است در ارجاع یادداشت‌های جاری ادغام شود) حل می‌کند.

استراتژی union تعارض‌های یادداشت را با اتصال نسخه‌های محلی و ریموت به یکدیگر به‌طور خودکار حل می‌کند.

استراتژی cat_sort_uniq شبیه به union است، اما علاوه بر اتصال نسخه‌های محلی و ریموت، خطوط حاصل را نیز مرتب کرده و خطوط تکراری را از نتیجه حذف می‌کند. این معادل اعمال پایپ‌لاین پوسته "cat | sort | uniq" بر روی نسخه‌های محلی و ریموت است. این استراتژی در صورتی مفید است که یادداشت‌ها از قالبی خط‌محور پیروی کنند که فرد بخواهد از خطوط تکراری در نتیجه ادغام جلوگیری کند. توجه داشته باشید که اگر هر یک از نسخه‌های محلی یا ریموت پیش از ادغام شامل خطوط تکراری باشند، آن‌ها نیز توسط این استراتژی ادغام یادداشت‌ها حذف خواهند شد.

مثال‌ها (EXAMPLES)

می‌توانید از یادداشت‌ها برای اضافه کردن حاشیه‌نویسی‌هایی با اطلاعاتی که در زمان نوشتن کامیت در دسترس نبوده‌اند استفاده کنید.

$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
$ git show -s 72a144e
[...]
    Signed-off-by: Junio C Hamano <gitster@pobox.com>
Notes:
    Tested-by: Johannes Sixt <j6t@kdbg.org>

در اصل، یک یادداشت یک blob معمولی Git است و هر نوع قالبی (یا غیرقالبی) پذیرفته می‌شود. شما می‌توانید با استفاده از git hash-object یادداشت‌هایی ایمن برای داده‌های باینری از فایل‌های دلخواه بسازید:

$ cc *.c
$ blob=$(git hash-object -w a.out)
$ git notes --ef=built add --llow-empty -C "$blob" HEAD

(شما نمی‌توانید به‌سادگی از git notes --ef=built add -F a.out HEAD استفاده کنید زیرا این دستور ایمن در برابر باینری نیست.) البته، نمایش یادداشت‌های غیرمتنی با git log چندان منطقی نیست، بنابراین اگر از چنین یادداشت‌هایی استفاده می‌کنید، احتمالاً باید ابزارهای ویژه‌ای برای انجام کارهای مفید با آن‌ها بنویسید.

پیکربندی (CONFIGURATION)

core.notesRef

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

notes.mergeStrategy

notes.<name>.mergeStrategy

notes.displayRef

notes.rewrite.<command>

notes.rewriteMode

notes.rewriteRef

محیط (ENVIRONMENT)

GIT_NOTES_REF

GIT_NOTES_DISPLAY_REF

GIT_NOTES_REWRITE_MODE

GIT_NOTES_REWRITE_REF

گیت (GIT)

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

نکات (NOTES)

1.

نام‌های مسیر مجاز دارای فرمت bf/fe/30/.../680d5a... هستند: توالی از نام‌های دایرکتوری با دو رقم هگزادسیمال که در ادامه نام فایلی با بقیه شناسه شیء (Object ID) قرار دارد.