نام (NAME)

git-filter-branch - بازنویسی شاخه‌ها

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

git filter-branch [--setup <command>] [--subdirectory-filter <directory>]
        [--env-filter <command>] [--tree-filter <command>]
        [--index-filter <command>] [--parent-filter <command>]
        [--msg-filter <command>] [--commit-filter <command>]
        [--tag-name-filter <command>] [--prune-empty]
        [--original <namespace>] [-d <directory>] [-f | --force]
        [--state-branch <branch>] [--] [<rev-list-options>...]

هشدار (WARNING)

دستور git filter-branch دارای دام‌های فراوانی است که می‌توانند منجر به خرابی‌های غیرواضح در بازنویسی هدفمند تاریخچه شوند (و به دلیل کارایی بسیار ضعیف آن، زمان اندکی برای بررسی چنین مشکلاتی برایتان باقی می‌گذارد). این مسائل امنیتی و عملکردی را نمی‌توان با حفظ سازگاری با گذشته اصلاح کرد و به همین دلیل، استفاده از آن توصیه نمی‌شود. لطفاً از یک ابزار جایگزین برای فیلتر کردن تاریخچه مانند git filter-repo[1] استفاده کنید. اگر همچنان نیاز به استفاده از git filter-branch دارید، لطفاً بخش «امنیت (SAFETY)» (و بخش «کارایی (PERFORMANCE)») را به دقت بخوانید تا با خطرات پنهان filter-branch آشنا شوید، و سپس تا جای ممکن و هوشیارانه از خطرات ذکرشده در آنجا اجتناب کنید.

توضیحات (DESCRIPTION)

به شما امکان می‌دهد تا با بازنویسی شاخه‌های ذکرشده در <rev-list-options> و اعمال فیلترهای سفارشی روی هر بازنگری، تاریخچه بازنگری‌های گیت را بازنویسی کنید. این فیلترها می‌توانند هر درخت (مانند حذف یک فایل یا اجرای یک اسکریپت بازنویسی perl روی تمام فایل‌ها) یا اطلاعات مربوط به هر کامیت را تغییر دهند. در غیر این صورت، تمام اطلاعات (از جمله زمان‌های اصلی کامیت یا اطلاعات ادغام) حفظ خواهند شد.

این دستور تنها ارجاع‌های مثبت ذکرشده در خط فرمان را بازنویسی خواهد کرد (برای مثال، اگر a..b را بدهید، تنها b بازنویسی می‌شود). اگر هیچ فیلتری مشخص نکنید، کامیت‌ها بدون هیچ تغییری دوباره ثبت می‌شوند که در حالت عادی هیچ اثری نخواهد داشت. با این وجود، این کار ممکن است در آینده برای جبران برخی باگ‌های گیت یا موارد مشابه مفید باشد، بنابراین چنین کاربردی مجاز است.

نکته: این دستور فایل .git/info/grafts و ارجاع‌های موجود در فضای نام refs/replace/ را محترم می‌شمارد. اگر پیوندها (grafts) یا ارجاع‌های جایگزینی تعریف کرده باشید، اجرای این دستور آن‌ها را دائمی خواهد کرد.

هشدار! تاریخچه بازنویسی‌شده دارای شناسه‌های شیء متفاوتی برای تمامی اشیاء خواهد بود و با شاخه اصلی همگرا نخواهد شد. شما نمی‌توانید به آسانی شاخه بازنویسی‌شده را روی شاخه اصلی ارسال (push) و توزیع کنید. اگر پیامدهای کامل آن را نمی‌دانید لطفاً از این دستور استفاده نکنید، و در هر صورت اگر یک کامیت ساده تکی برای حل مشکلتان کفایت می‌کند، از به‌کارگیری آن بپرهیزید. (برای اطلاعات بیشتر پیرامون بازنویسی تاریخچه منتشرشده، بخش "RECOVERING FROM UPSTREAM REBASE" را در git-rebase(1) ببینید.)

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

توجه داشته باشید که از آنجا که این عملیات از نظر ورودی/خروجی (I/O) بسیار سنگین است، انتقال مسیر پوشه موقت به خارج از دیسک با گزینه -d (برای مثال روی tmpfs) ایده خوبی خواهد بود. طبق گزارش‌ها، افزایش سرعت بسیار چشمگیر است.

گزینه‌ها (OPTIONS)

--setup <command>

--subdirectory-filter <directory>

--env-filter <command>

--tree-filter <command>

--index-filter <command>

--parent-filter <command>

--msg-filter <command>

--commit-filter <command>

--tag-name-filter <command>

--prune-empty

--original <namespace>

-d <directory>

-f, --force

--state-branch <branch>

<rev-list options>...

وضعیت خروج (EXIT STATUS)

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

مثال‌ها (EXAMPLES)

فرض کنید می‌خواهید فایلی (حاوی اطلاعات محرمانه یا نقض حق تکثیر) را از تمام کامیت‌ها حذف کنید:

git filter-branch --tree-filter 'rm filename' HEAD

با این حال، اگر فایل در درخت برخی از کامیت‌ها غایب باشد، یک دستور ساده rm filename برای آن درخت و کامیت ناموفق خواهد بود. بنابراین ممکن است بخواهید به جای آن از rm -f filename به عنوان اسکریپت استفاده کنید.

استفاده از --index-filter همراه با git rm نسخه‌ای به مراتب سریع‌تر را به دست می‌دهد. مشابه استفاده از rm filename، دستور git rm --cached filename نیز اگر فایل در درخت یک کامیت موجود نباشد، با شکست مواجه می‌شود. اگر می‌خواهید فایلی را «کاملاً به فراموشی بسپارید»، مهم نیست چه زمانی وارد تاریخچه شده است، بنابراین ما --ignore-unmatch را نیز می‌افزاییم:

git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD

اکنون، تاریخچه بازنویسی‌شده ذخیره‌شده در HEAD را در اختیار خواهید داشت.

برای بازنویسی مخزن به گونه‌ای که گویی foodir/ ریشه پروژه آن بوده است، و دور انداختن سایر بخش‌های تاریخچه:

git filter-branch --subdirectory-filter foodir -- --all

بدین ترتیب می‌توانید برای مثال، یک زیرپوشه کتابخانه را به مخزنی مستقل برای خود تبدیل کنید. به -- که گزینه‌های filter-branch را از گزینه‌های revision جدا می‌کند، و به --all برای بازنویسی تمام شاخه‌ها و برچسب‌ها دقت کنید.

برای تعیین یک کامیت (که معمولاً در رأس یک تاریخچه دیگر قرار دارد) به عنوان والد کامیت اولیه کنونی، جهت چسباندن تاریخچه دیگر در پشت سر تاریخچه جاری:

git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD

(اگر رشته والد خالی باشد - که هنگام برخورد با کامیت اولیه رخ می‌دهد - graftcommit را به عنوان والد بیفزا). توجه داشته باشید که این دستور فرض می‌کند تاریخچه دارای یک ریشه واحد است (یعنی هیچ ادغامی بدون اجداد مشترک رخ نداده است). در غیر این صورت، از این دستور استفاده کنید:

git filter-branch --parent-filter \
        'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD

یا حتی ساده‌تر:

git replace --graft $commit-id $graft-id
git filter-branch $graft-id..HEAD

برای حذف کامیت‌های ثبت‌شده توسط «Darl McBribe» از تاریخچه:

git filter-branch --commit-filter '
        if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
        then
                skip_commit "$@";
        else
                git commit-tree "$@";
        fi' HEAD

تابع skip_commit به صورت زیر تعریف شده است:

skip_commit()
{
        shift;
        while [ -n "$1" ];
        do
                shift;
                map "$1";
                shift;
        done;
}

ترفند shift ابتدا شناسه tree و سپس پارامترهای -p را دور می‌اندازد. توجه کنید که این ترفند ادغام‌ها را به درستی مدیریت می‌کند! چنانچه Darl یک ادغام میان P1 و P2 را کامیت کرده باشد، این تغییر به درستی منتشر خواهد شد و تمام فرزندان آن ادغام، به جای کامیت ادغام، تبدیل به کامیت‌های ادغامی با والدینی متشکل از P1,P2 می‌شوند.

توجه تغییرات ایجادشده توسط کامیت‌ها که توسط کامیت‌های پسین لغو (revert) نشده باشند، همچنان در شاخه بازنویسی‌شده باقی خواهند ماند. اگر می‌خواهید تغییرات را همراه با خود کامیت‌ها به دور بیندازید، باید از حالت تعاملی (interactive) دستور git rebase استفاده کنید.

می‌توانید پیام‌های گزارش کامیت را با استفاده از --msg-filter بازنویسی کنید. برای نمونه، رشته‌های git svn-id در مخزنی که توسط git svn ایجاد شده است را می‌توان به این صورت حذف نمود:

git filter-branch --msg-filter '
        sed -e "/^git-svn-id:/d"
'

چنانچه لازم است خطوط Acked-by را مثلاً به ۱۰ کامیت پایانی (که هیچ‌کدام ادغام نیستند) بیفزایید، از این دستور استفاده کنید:

git filter-branch --msg-filter '
        cat &&
        echo "Acked-by: Bugs Bunny <bunny@bugzilla.org>"
' HEAD~10..HEAD

گزینه --env-filter را می‌توان برای تغییر هویت ثبت‌کننده و/یا پدیدآورنده به کار برد. برای نمونه، اگر متوجه شدید که کامیت‌های شما به دلیل تنظیم نادرست user.email هویت اشتباهی دارند، پیش از انتشار پروژه می‌توانید تصحیحی به این صورت انجام دهید:

git filter-branch --env-filter '
        if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
        then
                GIT_AUTHOR_EMAIL=john@example.com
        fi
        if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
        then
                GIT_COMMITTER_EMAIL=john@example.com
        fi
' -- --all

برای محدود کردن بازنویسی تنها به بخشی از تاریخچه، یک بازه بازنگری (revision range) را علاوه بر نام شاخه جدید مشخص کنید. نام شاخه جدید به بالاترین بازنگری‌ای اشاره خواهد کرد که یک git rev-list از این بازه چاپ می‌کند.

این تاریخچه را در نظر بگیرید:

     D--E--F--G--H
    /     /
A--B-----C

برای بازنویسی تنها کامیت‌های D، E، F، G و H، اما دست‌نخورده گذاشتن A، B و C، از این دستور استفاده کنید:

git filter-branch ... C..H

برای بازنویسی کامیت‌های E، F، G و H، از یکی از این دستورات استفاده کنید:

git filter-branch ... C..H --not D
git filter-branch ... D..H --not C

برای انتقال تمام ساختار درخت به یک زیرپوشه، یا حذف آن از آنجا:

git filter-branch --index-filter \
        'git ls-files -s | sed "s-\t\"*-&newsubdir/-" |
                GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
                        git update-index --index-info &&
         mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' HEAD

فهرست بررسی برای کوچک‌سازی مخزن (CHECKLIST FOR SHRINKING A REPOSITORY)

می‌توان از git-filter-branch برای خلاص شدن از زیرمجموعه‌ای از فایل‌ها استفاده کرد، معمولاً با ترکیبی از --index-filter و --subdirectory-filter. افراد انتظار دارند مخزن حاصل کوچک‌تر از نسخه اولیه باشد، اما برای کوچک‌تر کردن واقعی آن به چند مرحله دیگر نیاز دارید، زیرا گیت سخت تلاش می‌کند اشیاء شما را تا زمانی که صراحتاً نگویید از دست ندهد. نخست مطمئن شوید که:

سپس دو راه برای رسیدن به مخزنی کوچک‌تر وجود دارد. راه ایمن‌تر شبیه‌سازی (clone) است، که نسخه اصلی شما را دست‌نخورده نگه می‌دارد.

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

کارایی (PERFORMANCE)

کارایی git-filter-branch بسیار کُند و لاک‌پشتی است؛ طراحی آن باعث می‌شود که یک پیاده‌سازی سازگار با گذشته هرگز نتواند سریع باشد:

ابزار git filter-repo[1] جایگزینی برای git-filter-branch است که از این مشکلات عملکردی یا مشکلات امنیتی (که در زیر ذکر شده) رنج نمی‌برد. برای کسانی که ابزارهای موجود مبتنی بر git-filter-branch دارند، git filter-repo همچنین filter-lamely[2] را ارائه می‌دهد که یک جایگزین مستقیم برای git-filter-branch است (با چند نکته قابل توجه). اگرچه filter-lamely از تمام همان مشکلات امنیتی git-filter-branch رنج می‌برد، اما دست‌کم کمی از مشکلات عملکردی را التیام می‌بخشد.

امنیت (SAFETY)

دستور git-filter-branch پر از دام‌هایی است که منجر به روش‌های مختلفی برای خراب کردن آسان مخازن یا رسیدن به وضعیتی به مراتب آشفته‌تر از آنچه شروع کرده‌اید می‌شود:

همچنین، عملکرد ضعیف git-filter-branch اغلب منجر به مسائل امنیتی می‌شود:

GIT

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

نکات (NOTES)

1.

git filter-repo

2.

filter-lamely