نام (NAME)

git-push - به‌روزرسانی ارجاع‌های دوردست همراه با اشیاء مرتبط

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

git push [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
         [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose]
         [-u | --set-upstream] [-o <string> | --push-option=<string>]
         [--[no-]signed | --signed=(true|false|if-asked)]
         [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]]
         [--no-verify] [<repository> [<refspec>...]]

توضیحات (DESCRIPTION)

یک یا چند شاخه، برچسب یا سایر ارجاع‌ها را در یک یا چند مخزن دوردست از مخزن محلی شما به‌روزرسانی می‌کند و تمام داده‌های لازم را که از قبل روی مخزن دوردست وجود ندارند ارسال می‌نماید.

ساده‌ترین روش برای ارسال، استفاده از دستور git push <remote> <branch> است. دستور git push origin main شاخه محلی main را به شاخه main در مخزن دوردست با نام origin ارسال می‌کند.

همچنین می‌توانید با استفاده از یک گروه مخزن دوردست (remote group)، به‌طور همزمان به چندین مخزن دوردست ارسال انجام دهید. یک گروه مخزن دوردست، فهرستی نام‌گذاری‌شده از مخازن دوردست است که از طریق remotes.<name> در پیکربندی گیت شما تنظیم می‌شود:

$ git config remotes.all-remotes "origin gitlab backup"

سپس دستور git push all-remotes به نوبت به origin، gitlab و backup ارسال انجام می‌دهد، گویی که git push را برای هر یک به صورت جداگانه اجرا کرده باشید. ارسال به هر مخزن دوردست به‌طور مستقل با استفاده از پیکربندی نگاشت ارسال (push mapping) مخصوص به خود انجام می‌شود. یک مدخل remotes.<group> در فایل پیکربندی وجود دارد. (به git-config(1) مراجعه کنید).

مقدار پیش‌فرض آرگومان <repository>، مخزن بالادست (upstream) برای شاخه جاری است، یا اگر بالادستی پیکربندی نشده باشد، برابر با origin خواهد بود.

برای تصمیم‌گیری درباره اینکه کدام شاخه‌ها، برچسب‌ها یا سایر ارجاع‌ها ارسال شوند، Git به ترتیب اولویت از موارد زیر استفاده می‌کند:

بسته به اینکه push.default روی چه مقداری تنظیم شده باشد، اگر بالادست (upstream) را برای شاخه جاری تنظیم نکرده باشید ممکن است اجرای git push با شکست مواجه شود. برای اطلاعات بیشتر در مورد نحوه تنظیم و استفاده از بالادست‌ها به بخش «شاخه‌های بالادست (UPSTREAM BRANCHES)» در زیر مراجعه کنید.

می‌توانید با تنظیم قلاب‌ها (hooks) در یک مخزن، کاری کنید که با هر بار ارسال (push) به آن، رویدادهای سفارشی مدنظرتان اجرا شوند. به مستندات git-receive-pack(1) مراجعه کنید.

گزینه‌ها (OPTIONS)

<repository>

<refspec>...

همهٔ به‌روزرسانی‌ها مجاز نیستند: برای جزئیات بخش PUSH RULES را در زیر ببینید.

--all, --branches

--prune

--mirror

-n, --dry-run

--porcelain

-d, --delete

--tags

--follow-tags

--signed, --no-signed, --signed=(true|false|if-asked)

--atomic, --no-atomic

-o <option>, --push-option=<option>

--receive-pack=<git-receive-pack>, --exec=<git-receive-pack>

--force-with-lease, --no-force-with-lease, --force-with-lease=<refname>, --force-with-lease=<refname>:<expect>

git remote add origin-push $(git config remote.origin.url)
git fetch origin-push

git push --force-with-lease origin-push

git fetch              # update 'master' from remote
git tag base master    # mark our base point
git rebase -i master   # rewrite some commits
git push --force-with-lease=master:base master:master

-f, --force

--force-if-includes, --no-force-if-includes

--repo=<repository>

-u, --set-upstream

--thin, --no-thin

-q, --quiet

-v, --verbose

--progress

--no-recurse-submodules, --recurse-submodules=(check|on-demand|only|no)

--verify, --no-verify

-4, --ipv4

-6, --ipv6

نشانی‌های وب گیت (GIT URLS)

به‌طور کلی، نشانی‌ها (URL) حاوی اطلاعاتی درباره پروتکل انتقال، نشانی سرور دوردست و مسیر مخزن هستند. بسته به پروتکل انتقال، ممکن است برخی از این اطلاعات وجود نداشته باشند.

گیت از پروتکل‌های ssh، git، http و https پشتیبانی می‌کند (علاوه بر این، ftp و ftps می‌توانند برای واکشی استفاده شوند، اما این کار ناکارآمد و منسوخ است؛ از آن‌ها استفاده نکنید).

انتقال بومی (یعنی نشانی git://) هیچ‌گونه احراز هویتی انجام نمی‌دهد و باید در شبکه‌های ناامن با احتیاط استفاده شود.

نحوهای زیر می‌توانند با آن‌ها استفاده شوند:

همچنین می‌توان یک نحو جایگزین شبیه scp را با پروتکل ssh استفاده کرد:

این نحو تنها در صورتی تشخیص داده می‌شود که هیچ اسلشی قبل از اولین دونقطه نباشد. این امر به تمایز مسیر محلی که حاوی دونقطه است کمک می‌کند. برای نمونه، مسیر محلی foo:bar می‌تواند به‌صورت یک مسیر مطلق یا ./foo:bar مشخص شود تا از تفسیر نادرست آن به‌عنوان یک نشانی ssh جلوگیری شود.

پروتکل‌های ssh و git علاوه بر این از بسط ~<username> پشتیبانی می‌کنند:

برای مخازن محلی، که به‌طور بومی توسط گیت نیز پشتیبانی می‌شوند، می‌توان از نحوهای زیر استفاده کرد:

این دو نحو عمدتاً معادل هستند، به جز هنگام کلون کردن که اولی متضمن گزینه --local است. برای جزئیات به git-clone(1) مراجعه کنید.

دستورهای git clone، git fetch و git pull (اما نه git push) یک فایل باندل مناسب را نیز می‌پذیرند. به git-bundle(1) مراجعه کنید.

هنگامی که گیت روش کار با یک پروتکل انتقال معین را نمی‌داند، تلاش می‌کند از دستیار دوردست remote-<transport> در صورت وجود استفاده کند. برای درخواست صریح یک دستیار دوردست، می‌توان از نحو زیر استفاده کرد:

که در آن <address> می‌تواند یک مسیر، یک سرور و مسیر، یا یک رشته دلخواه شبیه نشانی باشد که توسط دستیار دوردست مربوطه فراخوانی‌شده شناسایی می‌شود. برای جزئیات به gitremote-helpers(7) مراجعه کنید.

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

[url "<actual-url-base>"]
        insteadOf = <other-url-base>

برای نمونه، با این تنظیم:

[url "git://git.host.xz/"]
        insteadOf = host.xz:/path/to/
        insteadOf = work:

یک نشانی مانند "work:repo.git" یا مانند "host.xz:/path/to/repo.git" در هر زمینه‌ای که یک نشانی می‌پذیرد به "git://git.host.xz/repo.git" بازنویسی خواهد شد.

اگر می‌خواهید نشانی‌ها را فقط برای ارسال (push) بازنویسی کنید، می‌توانید یک بخش پیکربندی به این شکل بسازید:

[url "<actual-url-base>"]
        pushInsteadOf = <other-url-base>

برای نمونه، با این تنظیم:

[url "ssh://example.org/"]
        pushInsteadOf = git://example.org/

یک نشانی مانند "git://example.org/path/to/repo.git" برای ارسال‌ها به "ssh://example.org/path/to/repo.git" بازنویسی می‌شود، اما دریافت‌ها (pull) همچنان از نشانی اصلی استفاده خواهند کرد.

مخازن دوردست (REMOTES)

نام یکی از موارد زیر می‌تواند به عنوان آرگومان <repository> به‌جای نشانی (URL) استفاده شود:

همه این موارد همچنین به شما این امکان را می‌دهند که مشخصه ارجاع (refspec) را از خط فرمان حذف کنید زیرا هر یک از آن‌ها حاوی یک مشخصه ارجاع هستند که گیت به‌طور پیش‌فرض از آن استفاده خواهد کرد.

[remote "<name>"]
        url = <URL>
        pushurl = <pushurl>
        push = <refspec>
        fetch = <refspec>

URL: one of the above URL formats
Push: <refspec>
Pull: <refspec>

<URL>#<head>

refs/heads/<head>:refs/heads/<branch>

HEAD:refs/heads/<head>

شاخه‌های بالادست (UPSTREAM BRANCHES)

شاخه‌ها در گیت می‌توانند به‌طور اختیاری دارای یک شاخه دوردست بالادست باشند. گیت به‌طور پیش‌فرض برای عملیات‌های دوردست از شاخه بالادست استفاده می‌کند، به عنوان مثال:

شاخه بالادست در .git/config، در فیلدهای "remote" و "merge" ذخیره می‌شود. به عنوان مثال، اگر شاخه بالادستِ main برابر با origin/main باشد:

[branch "main"]
   remote = origin
   merge = refs/heads/main

شما می‌توانید با استفاده از git push --set-upstream <remote> <branch> یک شاخه بالادست را صریحاً تنظیم کنید، اما گیت در اغلب موارد به‌طور خودکار شاخه بالادست را برای شما تنظیم می‌کند؛ برای مثال:

گروه‌های دوردست (REMOTE GROUPS)

یک گروه دوردست، فهرستی نام‌گذاری‌شده از مخازن دوردست است که از طریق remotes.<name> در پیکربندی گیت شما تنظیم می‌شود:

$ git config remotes.all-remotes "r1 r2 r3"

هنگامی که یک نام گروه به عنوان آرگومان <repository> داده می‌شود، ارسال به نوبت برای هر یک از مخازن دوردستِ عضو گروه انجام می‌گیرد. اصل حاکم این است که:

git push <options> all-remotes <args>

دقیقاً معادل است با:

git push <options> r1 <args>
git push <options> r2 <args>
...
git push <options> rN <args>

که در آن r1، r2، ...، rN اعضای all-remotes هستند. هیچ رفتار خاصی اضافه یا حذف نمی‌شود — گروه صرفاً یک میانبر برای اجرای جداگانه همان دستور push در برابر هر مخزن دوردست عضو است.

هنگام ارسال به گروهی متشکل از بیش از یک مخزن دوردست، گیت به ترتیب برای هر مخزن دوردست عضو یک زیرفرآیند مجزای git push ایجاد می‌کند. هر زیرفرآیند همان پرچم‌ها و مشخصه‌های ارجاع مربوط به فراخوانی اولیه را دریافت می‌کند. این بدان معناست که نگاشت‌های ارسال اختصاصی هر مخزن دوردست که از طریق remote.<name>.push پیکربندی شده‌اند و حالت آینه‌ای (remote.<name>.mirror) به‌طور مستقل برای هر مخزن دوردست ارزیابی می‌شوند، و یک مخزن دوردست آینه‌ای در گروه نمی‌تواند بر رفتار ارسال سایر مخازن دوردست غیرآینه‌ای در همان گروه تأثیر بگذارد.

گزینه --atomic برای ارسال‌های گروهی پشتیبانی نمی‌شود، زیرا اتمیک بودن (اتمام یکپارچه) تنها در قالب یک اتصال انتقال واحد به یک مخزن دوردست منفرد قابل تضمین است. اگر --atomic همراه با یک نام گروه ترکیب شود، گیت فراخوانی را با یک خطا رد خواهد کرد.

اگر هر یک از مخازن دوردستِ عضو با شکست مواجه شود، خواه به دلیل رد شدن ارسال (مانند یک به‌روزرسانی غیر fast-forward یا هوک سمت سرور که یک ارجاع را رد می‌کند) یا خطای اتصال (مانند عدم وجود مخزن، شکست در احراز هویت، یا در دسترس نبودن شبکه)، گیت خطا را گزارش داده و به ارسال به باقی مخازن دوردست در گروه ادامه می‌دهد. در صورتی که ارسال به هر یک از اعضا ناموفق باشد، کد خروج کلی غیرصفر خواهد بود.

این بدان معناست که کاربر مسئول اطمینان از معقول بودن توالی ارسال‌های جداگانه است. اگر git push r1 برای مجموعه‌ای معین از گزینه‌ها و آرگومان‌ها با شکست مواجه شود، آن‌گاه git push all-remotes نیز هنگام رسیدن به r1 به همان شیوه با شکست مواجه خواهد شد. ارسال گروهی کار خاصی برای به موفقیت رساندن یک ارسالِ انفرادیِ ناموفق انجام نمی‌دهد.

خروجی (OUTPUT)

خروجی «git push» به روش انتقال مورد استفاده بستگی دارد؛ این بخش خروجی را هنگام ارسال بر روی پروتکل گیت (چه به صورت محلی و چه از طریق ssh) توضیح می‌دهد.

وضعیت ارسال به صورت جدولی خروجی داده می‌شود، به طوری که هر خط نشان‌دهنده وضعیت یک ارجاع منفرد است. هر خط به این صورت است:

<flag> <summary> <from> -> <to> (<reason>)

اگر از --porcelain استفاده شود، آن‌گاه هر خط از خروجی به این صورت خواهد بود:

<flag> \t <from>:<to> \t <summary> (<reason>)

وضعیت ارجاع‌های به‌روز تنها در صورتی نمایش داده می‌شود که گزینه --porcelain یا --verbose استفاده شده باشد.

<flag>

<summary>

from

to

reason

قوانین ارسال (PUSH RULES)

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

از آنجا که شاخه‌ها و برچسب‌ها برای کاربردهای متفاوتی در نظر گرفته شده‌اند، قوانین ایمنی برای ارسال به یک شاخه با قوانین ارسال به یک برچسب متفاوت است. در قوانین زیر «به‌روزرسانی» به معنای هرگونه تغییر به جز حذف و ایجاد است. حذف و ایجاد همیشه مجاز است، مگر زمانی که توسط پیکربندی یا قلاب‌ها ممنوع شده باشد.

شما می‌توانید این قوانین را با ارسال --force یا با افزودن + اختیاری در ابتدای یک مشخصه ارجاع (refspec) نادیده بگیرید. تنها استثناها این است که هیچ مقداری از اجبار کردن باعث نخواهد شد یک شاخه شیئی غیر از کامیت را بپذیرد، و اجبار کردن باعث نخواهد شد مخزن دوردست ارسالی را بپذیرد که برای رد آن پیکربندی شده است.

قلاب‌ها و پیکربندی نیز می‌توانند این قوانین را لغو کرده یا اصلاح کنند؛ برای نمونه receive.denyNonFastForwards و receive.denyDeletes را در git-config(1) و pre-receive و update در githooks(5) ببینید.

نکته‌ای درباره جلوبردن‌های سریع (NOTE ABOUT FAST-FORWARDS)

هنگامی که یک به‌روزرسانی، شاخه‌ای (یا به‌طور کلی‌تر، یک ارجاع) را که به کامیت A اشاره می‌کرد تغییر می‌دهد تا به کامیت دیگری مانند B اشاره کند، این عملیات اگر و تنها اگر B نواده‌ای از A باشد، یک به‌روزرسانی جلوبردن سریع (fast-forward) نامیده می‌شود.

در یک به‌روزرسانی جلوبردن سریع از A به B، مجموعه کامیت‌هایی که کامیت اولیه A بر پایه آن‌ها ساخته شده بود، زیرمجموعه‌ای از کامیت‌هایی است که کامیت جدید B بر روی آن‌ها بنا شده است. از این رو، هیچ تاریخچه‌ای از دست نمی‌رود.

در مقابل، یک به‌روزرسانی جلوبردن غیرسریع (non-fast-forward) تاریخچه را از بین خواهد برد. برای نمونه، فرض کنید شما و فرد دیگری کار را از کامیت یکسان X آغاز کرده‌اید، و شما تاریخچه‌ای ساخته‌اید که به کامیت B می‌رسد، در حالی که فرد دیگر تاریخچه‌ای منتهی به کامیت A ساخته است. این تاریخچه به این شکل است:

     B
    /
---X---A

همچنین فرض کنید آن فرد دیگر پیش‌تر تغییرات منتهی به A را به مخزن اصلی که شما دو نفر کامیت اولیه X را از آن دریافت کرده بودید، ارسال (push) کرده است.

ارسالِ انجام‌شده توسط فرد دیگر، شاخه‌ای را که به کامیت X اشاره می‌کرد به‌روزرسانی کرده تا به کامیت A اشاره کند. این یک جلوبردن سریع (fast-forward) است.

اما اگر شما برای ارسال تلاش کنید، سعی خواهید کرد شاخه را (که اکنون به A اشاره دارد) با کامیت B به‌روزرسانی نمایید. این عملیات جلوبردن سریع نخواهد بود. اگر چنین کاری می‌کردید، تغییرات ایجادشده توسط کامیت A از دست می‌رفت، زیرا از این پس همگان کار را بر پایه B ادامه می‌دادند.

این دستور به‌طور پیش‌فرض اجازه به‌روزرسانی غیرسریع را نمی‌دهد تا از چنین از دست رفتن تاریخچه‌ای جلوگیری کند.

اگر نمی‌خواهید کار خودتان (تاریخچه از X به B) یا کار فرد دیگر (تاریخچه از X به A) را از دست بدهید، باید ابتدا تاریخچه را از مخزن واکشی (fetch) کنید، تاریخچه‌ای بسازید که شامل تغییرات انجام‌شده توسط هر دو طرف باشد، و سپس نتیجه را ارسال (push) کنید.

می‌توانید دستور "git pull" را اجرا کنید، تداخل‌های احتمالی را برطرف نمایید، و نتیجه را با "git push" ارسال کنید. دستور "git pull" یک کامیت ادغام C بین کامیت‌های A و B ایجاد خواهد کرد.

     B---C
    /   /
---X---A

به‌روزرسانی A با کامیت ادغام حاصل‌شده، به‌صورت جلوبردن سریع خواهد بود و ارسال (push) شما پذیرفته می‌شود.

به عنوان روش دیگر، می‌توانید با استفاده از git pull --rebase تغییرات خود بین X و B را بر روی A بازپایه‌ریزی (rebase) کرده و نتیجه را ارسال (push) نمایید. این بازپایه‌ریزی یک کامیت جدید D ایجاد می‌کند که تغییرات بین X و B را بر روی A بنا می‌سازد.

     B   D
    /   /
---X---A

مجدداً، به‌روزرسانی A با این کامیت یک جلوبردن سریع خواهد بود و ارسال شما پذیرفته می‌شود.

وضعیت رایج دیگری نیز وجود دارد که ممکن است هنگام تلاش برای ارسال (push) با رد شدن به دلیل جلوبردن غیرسریع مواجه شوید، و این حالت حتی زمانی که به مخزنی ارسال می‌کنید که هیچ‌کس دیگری به آن ارسال نمی‌کند نیز امکان‌پذیر است. پس از این‌که خودتان کامیت A را ارسال کردید (در تصویر نخست این بخش)، آن را با git commit --amend جایگزین می‌کنید تا کامیت B تولید شود، و سپس تلاش می‌کنید آن را ارسال کنید چون فراموش کرده‌اید که پیش‌تر A را ارسال کرده بودید. در چنین حالتی، و تنها اگر مطمئن هستید که در این فاصله هیچ‌کس کامیت قبلی شما یعنی A را واکشی (fetch) نکرده است (و ساخت کار خود را بر روی آن آغاز نکرده است)، می‌توانید git push --force را برای رونویسی روی آن اجرا کنید. به عبارت دیگر، git push --force روشی است که برای مواردی در نظر گرفته شده که شما واقعاً قصد دارید تاریخچه را از دست بدهید.

مثال‌ها (EXAMPLES)

git push

git push origin

git push origin :

git push origin master

git push origin HEAD

git push mothership master:satellite/master dev:satellite/dev

git push origin HEAD:master

git push origin master:refs/heads/experimental

git push origin :experimental

git push origin +dev:master

o---o---o---A---B  origin/master
         \
          X---Y---Z  dev

          A---B  (unnamed branch)
         /
o---o---o---X---Y---Z  master

امنیت (SECURITY)

پروتکل‌های fetch و push برای جلوگیری از سرقت داده‌هایی از مخزن طرف مقابل که قصد به‌اشتراک‌گذاری آن‌ها نبوده است طراحی نشده‌اند. اگر داده‌های خصوصی دارید که باید از یک همتای مخرب محافظت شوند، بهترین گزینه شما ذخیره آن‌ها در یک مخزن دیگر است. این امر هم برای کلاینت‌ها و هم برای سرورها صدق می‌کند. به‌ویژه، فضاهای نام (namespaces) روی یک سرور برای کنترل دسترسی خواندن کارآمد نیستند؛ شما فقط باید دسترسی خواندن به یک فضای نام را به کلاینت‌هایی اعطا کنید که برای دسترسی خواندن به کل مخزن به آن‌ها اعتماد دارید.

بردارهای حمله شناخته‌شده به شرح زیر هستند:

پیکربندی (CONFIGURATION)

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

push.autoSetupRemote

push.default

push.followTags

push.gpgSign

push.pushOption

مثال:
/etc/gitconfig
  push.pushoption = a
  push.pushoption = b
~/.gitconfig
  push.pushoption = c
repo/.git/config
  push.pushoption =
  push.pushoption = b
این تنظیم تنها منجر به b خواهد شد (a و c پاک می‌شوند).

push.recurseSubmodules

push.useForceIfIncludes

push.negotiate

push.useBitmaps

گیت (GIT)

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