نام (NAME)

git-check-ref-format - اطمینان از ساختار صحیح و معتبر بودن نام یک ارجاع

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

git check-ref-format [--normalize]
       [--[no-]allow-onelevel] [--refspec-pattern]
       <refname>
git check-ref-format --branch <branchname-shorthand>

توضیحات (DESCRIPTION)

بررسی می‌کند که آیا یک refname (نام ارجاع) مشخص قابل قبول است یا خیر، و اگر نباشد با وضعیت غیرصفر خارج می‌شود.

در گیت از یک ارجاع برای مشخص کردن شاخه‌ها و برچسب‌ها استفاده می‌شود. نوک یک شاخه در سلسله‌مراتب refs/heads ذخیره می‌شود، در حالی که یک برچسب در سلسله‌مراتب refs/tags از فضای‌نام ارجاع نگهداری می‌گردد (معمولاً در دایرکتوری‌های $GIT_DIR/refs/heads و $GIT_DIR/refs/tags یا در صورت بسته‌بندی ارجاع‌ها توسط git gc، به عنوان ورودی‌هایی در فایل $GIT_DIR/packed-refs).

گیت قوانین زیر را در نحوه نام‌گذاری ارجاع‌ها اعمال می‌کند:

1.آن‌ها می‌توانند شامل اسلش / برای دسته‌بندی سلسله‌مراتبی (دایرکتوری) باشند، اما هیچ مؤلفه جداشده با اسلش نمی‌تواند با یک نقطه . شروع شود یا به توالی .lock ختم گردد.

2.آن‌ها باید حداقل شامل یک / باشند. این امر وجود یک دسته‌بندی مانند heads/، tags/ و غیره را الزامی می‌کند، اما نام‌های واقعی محدودیتی ندارند. اگر از گزینه --allow-onelevel استفاده شود، این قانون نادیده گرفته می‌شود.

3.آن‌ها نمی‌توانند در هیچ‌کجای خود دو نقطه متوالی .. داشته باشند.

4.آن‌ها نمی‌توانند در هیچ‌کجای خود نویسه‌های کنترلی اسکی (یعنی بایت‌هایی با مقدار کمتر از \040 یا \177 DEL)، فاصله، مدک (تیلدا) ~، هشتک (کارِت) ^، یا دونقطه : داشته باشند.

5.آن‌ها نمی‌توانند در هیچ‌کجای خود علامت سوال ?، ستاره *، یا براکت باز [ داشته باشند. برای استثنای این قانون به گزینه --refspec-pattern در زیر مراجعه کنید.

6.آن‌ها نمی‌توانند با یک اسلش / شروع یا تمام شوند، یا شامل چندین اسلش متوالی باشند (برای استثنای این قانون به گزینه --normalize در زیر مراجعه کنید).

7.آن‌ها نمی‌توانند با یک نقطه . به پایان برسند.

8.آن‌ها نمی‌توانند شامل توالی @{ باشند.

9.آن‌ها نمی‌توانند تک‌نویسه @ باشند.

10.آن‌ها نمی‌توانند شامل یک \ باشند.

این قوانین تجزیه نام‌های ارجاع را برای ابزارهای مبتنی بر اسکریپت شل، بسط نام مسیر توسط شل هنگامی که نام ارجاع بدون گیومه (به اشتباه) استفاده شده باشد، آسان‌تر کرده و همچنین از ابهامات در برخی عبارت‌های نام ارجاع جلوگیری می‌کنند (به gitrevisions(7) مراجعه کنید):

1.دو نقطه متوالی .. اغلب مانند ref1..ref2 استفاده می‌شود و در برخی زمینه‌ها این نمادگذاری به معنای ^ref1 ref2 است (یعنی در ref1 نباشد و در ref2 باشد).

2.مدک (تیلدا) ~ و هشتک (کارِت) ^ برای معرفی پسوند والد N-ام (nth parent) و عملیات پوست کندن پیاز (peel onion) استفاده می‌شوند.

3.دونقطه : مانند srcref:dstref در عملیات واکشی (fetch) و ارسال (push) به معنای «استفاده از مقدار srcref و ذخیره آن در dstref» به کار می‌رود. همچنین ممکن است برای انتخاب یک شیء مشخص مانند git cat-file استفاده شود: "git cat-file blob v1.3.3:refs.c".

4.آکولاد باز پس از ات‌ساین @{ به عنوان نمادگذاری برای دسترسی به یک ورودی reflog استفاده می‌شود.

با گزینه --branch، این دستور یک نام را می‌گیرد و بررسی می‌کند که آیا می‌توان از آن به عنوان یک نام شاخه معتبر استفاده کرد یا خیر (مثلاً هنگام ایجاد یک شاخه جدید). اما هنگام استفاده از نحو بررسی پیشین (previous checkout syntax) که ممکن است به وضعیت سر جداشده (detached HEAD) اشاره کند، محتاط باشید. قانونی که git check-ref-format --branch $name پیاده‌سازی می‌کند ممکن است سخت‌گیرانه‌تر از آن چیزی باشد که git check-ref-format refs/heads/$name اعلام می‌دارد (برای مثال، خط تیره ممکن است در ابتدای یک مؤلفه ارجاع ظاهر شود، اما در ابتدای نام شاخه صراحتاً ممنوع است). هنگام اجرا با گزینه --branch در یک مخزن، ورودی ابتدا برای نحو «بررسی پیشین» @{-n} بسط می‌یابد. به عنوان مثال، @{-1} روشی برای اشاره به آخرین موردی است که با استفاده از عملیات "git switch" یا "git checkout" خارج شده است. این گزینه باید توسط ابزارهای سطح بالاتر (porcelains) برای پذیرش این نحو در هر جایی که نام شاخه انتظار می‌رود استفاده شود تا بتوانند به گونه‌ای عمل کنند که گویی شما نام شاخه را تایپ کرده‌اید. به عنوان یک استثنا توجه داشته باشید که عملیات «بررسی پیشین» ممکن است زمانی که N-امین مورد قبلی بررسی‌شده یک شاخه نبوده، به نام یک شیء کامیت ختم شود.

گزینه‌ها (OPTIONS)

--allow-onelevel, --no-allow-onelevel

کنترل اینکه آیا نام‌های ارجاع تک‌سطحی پذیرفته شوند یا خیر (یعنی نام‌های ارجاعی که شامل چندین مؤلفه جداشده با / نیستند). مقدار پیش‌فرض --no-allow-onelevel است.

--refspec-pattern

تفسیر <refname> به عنوان الگوی نام ارجاع برای یک مشخصه ارجاع (refspec - همان‌طور که با مخازن دوردست استفاده می‌شود). اگر این گزینه فعال باشد، <refname> مجاز است شامل یک ستاره تکی * در refspec باشد (مانند foo/bar*/baz یا foo/bar*baz/ اما نه foo/bar*/baz*).

--normalize

نرمال‌سازی refname با حذف نویسه‌های اسلش (/) ابتدایی و ادغام اسلش‌های متوالی بین مؤلفه‌های نام به یک اسلش واحد. اگر نام ارجاع نرمال‌شده معتبر باشد، آن را در خروجی استاندارد چاپ کرده و با وضعیت 0 خارج می‌شود، در غیر این صورت با وضعیت غیرصفر خارج خواهد شد. (--print روشی منسوخ‌شده برای نوشتن --normalize است.)

مثال‌ها (EXAMPLES)

•چاپ نام آخرین موردی که خارج (checked out) شده است:

$ git check-ref-format --branch @{-1}

•تعیین نام ارجاع برای استفاده در یک شاخه جدید:

$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch")||
{ echo "we do not like '$newbranch' as a branch name." >&2 ; exit 1 ; }

گیت (GIT)

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