نام (NAME)

syncthing-stignore - جلوگیری از همگام‌سازی فایل‌ها با گره‌های دیگر

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

.stignore

توضیحات (DESCRIPTION)

اگر نباید برخی فایل‌ها با سایر دستگاه‌ها همگام‌سازی شوند (یا از آن‌ها دریافت گردند)، می‌توان فایلی به نام .stignore حاوی الگوهای نادیده‌گیری فایل‌ها ایجاد کرد. فایل .stignore باید در ریشه پوشه همگام‌سازی قرار گیرد (فایل‌ها در مکان‌های دیگر اعمال نمی‌شوند). خود فایل .stignore هرگز با دستگاه‌های دیگر همگام‌سازی نمی‌شود، هرچند می‌تواند با #include فایل‌هایی را که بین دستگاه‌ها همگام‌سازی می‌شوند فراخوانی کند. تمام الگوها نسبت به ریشه پوشه همگام‌سازی سنجیده می‌شوند. محتویات فایل .stignore باید با کدبندی UTF-8 باشد.

نکته:

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

الگوها (PATTERNS)

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

نام‌های معمولی فایل با خودشان تطابق می‌یابند؛ به عنوان مثال، الگوی foo با فایل‌های foo، subdir/foo و هر دایرکتوری با نام foo تطابق دارد. فاصله‌ها به عنوان نویسه‌های معمولی در نظر گرفته می‌شوند، به جز فاصله‌های ابتدا و انتهای خط که به طور خودکار حذف می‌شوند.
ستاره (*) با صفر یا چند نویسه در نام فایل تطابق می‌یابد، اما با جداکننده دایرکتوری تطابق ندارد. الگوی te*ne با telephone و subdir/telephone تطابق دارد اما با tele/phone تطابق ندارد.
دو ستاره (**) مانند بالا تطابق می‌یابد، اما شامل جداکننده‌های دایرکتوری نیز می‌شود. الگوی te**ne با telephone، subdir/telephone و tele/sub/dir/phone تطابق دارد.
علامت سوال (?) با یک نویسه منفرد که جداکننده دایرکتوری نباشد تطابق می‌یابد. الگوی te??st با tebest تطابق دارد اما با teb/st یا test تطابق ندارد.
کروکوشه‌ها ([]) بیانگر محدوده‌ای از نویسه‌ها هستند: [a-z] با هر نویسه کوچک انگلیسی تطابق دارد.
آکولادها ({}) مجموعه‌ای از گزینه‌های جداشده با کاما را نشان می‌دهند: {banana,pineapple} با هر یک از مقادیر banana یا pineapple تطابق دارد.
اسلش رو به عقب (\) یک نویسه خاص را بی‌اثر (escape) می‌کند تا معنی خاص خود را از دست بدهد. به عنوان مثال، \{banana\} دقیقاً با {banana} تطابق دارد و مجموعه‌ای از گزینه‌ها مانند بالا به حساب نمی‌آید.
نکته:

در ویندوز، \ جداکننده مسیر است، بنابراین از | برای اسکیپ کردن نویسه‌های خاص استفاده کنید. به عنوان مثال، |{banana|} با {banana} مطابقت دارد.

برای استفاده از \ جهت اسکیپ نویسه‌های خاص (و استفاده از / به عنوان جداکننده مسیر)، عبارت #escape=\ را در بالای فایل درج کنید. مثال کوتاه:

#escape=\
/foo
/path/bar/\{banana\}
/path/baz\[2\]/ex\[3\].txt

عبارت #escape=\ باید در بالای فایل و پیش از هر الگویی قرار گیرد، هرچند توضیحات و خطوط خالی در ابتدا مجاز هستند.

هر فایلی که با دستور #include فراخوانی شود (پایین را ببینید) به عبارت #escape=\ اختصاصی خود نیاز خواهد داشت.

استفاده از #escape=\ امکان همگام‌سازی و استفاده از یک فایل مشترک را در هر سیستم‌عاملی فراهم می‌کند.

الگویی که با / آغاز شود تنها در ریشه پوشه همگام‌سازی مطابقت می‌یابد. /foo با foo مطابقت دارد اما با subdir/foo تطابق ندارد.
الگویی که با #include شروع شود، منجر به بارگذاری الگوها از فایل نام‌برده می‌شود. در صورت عدم وجود فایل یا درج بیش از یک بار، خطا رخ می‌دهد. توجه داشته باشید که هرچند می‌توان از این برای درج الگوها از یک فایل در زیرپوشه استفاده کرد، الگوها کماکان نسبت به ریشه پوشه همگام‌سازی سنجیده می‌شوند. مثال: #include more-patterns.txt.
هر دستور #include درون فایلی که بارگذاری می‌شود، به مسیرهایی نیاز دارد که نسبت به پوشه حاوی همان فایل مشخص شده باشند، نه نسبت به ریشه همگام‌سازی.
الگویی با پیشوند ! الگو را نفی می‌کند: فایل‌های منطبق درج می‌شوند (یعنی نادیده گرفته نمی‌شوند). این ویژگی می‌تواند برای بازنویسی الگوهای عمومی‌تر بعدی استفاده شود.
نکته:

الگوهای منفی که با اقلام پایین‌تر از ریشه پوشه تطابق دارند، باعث می‌شوند Syncthing پوشه‌هایی را که در غیر این صورت نادیده گرفته می‌شدند پیمایش کند. اگر ناظر (watcher) فعال باشد، آن پوشه‌ها نیز پایش می‌شوند. با این حال پوشه‌هایی که قبل از نخستین الگوی منفی نادیده گرفته شده‌اند، می‌توانند با خیال راحت نادیده انگاشته شوند زیرا اولین الگوی منطبق اولویت دارد. به عنوان مثال:

/foo
/bar
!baz
*

پوشه‌های foo و bar کاملاً نادیده گرفته خواهند شد. اما هر پوشه دیگر باید به طور کامل پویش شود تا موارد با نام baz پیدا شوند، علی‌رغم اینکه به دلیل الگوی * نادیده گرفته خواهند شد. به عنوان حالتی خاص، الگوهای ریشه‌ای سطح بالا (مانند !/foo) باعث این رفتار نمی‌شوند:

!/baz
*

در این حالت، فقط پوشه baz پویش می‌شود، زیرا همه موارد دیگر با الگوی * نادیده گرفته شده‌اند.

الگویی که با پیشوند (?i) شروع شود، تطبیق الگو را به حروف کوچک و بزرگ حساس نمی‌کند. الگوی (?i)test با test، TEST و tEsT تطابق دارد. پیشوند (?i) را می‌توان با الگوهای دیگر ترکیب کرد؛ مثلاً الگوی (?i)!picture*.png نشان می‌دهد که Picture1.PNG باید همگام‌سازی شود. در Mac OS و Windows، الگوها همیشه نسبت به حروف بزرگ و کوچک حساس نیستند.
الگویی با پیشوند (?d) حذف فایل‌ها را در صورتی که مانع حذف دایرکتوری شوند مجاز می‌کند. این پیشوند باید برای فایل‌های تولیدشده توسط سیستم‌عامل که حذف آن‌ها مشکلی ایجاد نمی‌کند استفاده شود.
نکته:

پیشوندها می‌توانند با هر ترتیبی مشخص شوند (مثلاً (?d)(?i))، اما نمی‌توان آن‌ها را درون یک جفت پرانتز ترکیب کرد (مانند (?di)).

•: خطی که با // آغاز شود یک توضیح (کامنت) است و اثری ندارد. دو اسلش در هر نقطه دیگر به صورت لغوی تفسیر می‌شوند؛ مثلاً درج file // comment باعث می‌شود Syncthing به دنبال فایلی با نام file // comment بگردد.

مثال (EXAMPLE)

با فرض ساختار پوشه‌ای زیر در ریشه پوشه همگام‌سازی:

.DS_Store
.stignore
foo
foofoo
bar/
    baz
    quux
    quuz
bar2/
    baz
    frobble
My Pictures/
    Img15.PNG

و فایلی به نام .stignore با محتویات زیر:

(?d).DS_Store
!frobble
!quuz
foo
*2
qu*
(?i)my pictures

تمام فایل‌ها و پوشه‌هایی با نام “foo”، پایان‌یافته با “2” یا شروع‌شده با “qu” نادیده گرفته خواهند شد. نتیجه نهایی به این صورت خواهد بود:

.DS_Store     # نادیده گرفته شد، در صورت جلوگیری از حذف پوشه والد حذف خواهد شد
foo           # نادیده گرفته شد، منطبق با "foo"
foofoo        # همگام‌سازی شد، با "foo" تطابق ندارد اما با "foo*" یا "*foo" تطابق داشت
bar/          # همگام‌سازی شد
    baz       # همگام‌سازی شد
    quux      # نادیده گرفته شد، منطبق با "qu*"
    quuz      # همگام‌سازی شد، با "qu*" تطابق دارد اما با الگوی قبلی "!quuz" استثنا شده
bar2/         # همگام‌سازی شد، علیرغم تطابق با "*2" به دلیل وجود فرزند frobble
    baz       # نادیده گرفته شد، به دلیل نادیده گرفته شدن والد
    frobble   # همگام‌سازی شد، به دلیل "!frobble"
My Pictures/  # نادیده گرفته شد، منطبق با الگوی حساس نبودن به حروف "(?i)my pictures"
    Img15.PNG # نادیده گرفته شد، به دلیل نادیده گرفته شدن والد

نکته:

لطفاً توجه داشته باشید که الگوهای دایرکتوری که با اسلش پایان می‌یابند مانند some/directory/ با محتوای دایرکتوری تطابق می‌یابند، نه خود دایرکتوری. اگر می‌خواهید الگو هم با دایرکتوری و هم با محتوای آن مطابقت یابد، اطمینان حاصل کنید که اسلش / در انتهای الگو نباشد.

اضافه‌شده در نسخه 1.19.0: می‌توان الگوهای پیش‌فرضی را پیکربندی کرد که هنگام پذیرش خودکار پوشه از یک دستگاه راه دور اعمال شوند. واسط گرافیکی (GUI) هنگام افزودن دستی پوشه نیز همین الگوها را پیشنهاد می‌دهد. در هر صورت، اگر فایلی وجود نداشته باشد، فایل .stignore با این مقادیر پیش‌فرض ایجاد می‌شود.

اضافه‌شده در نسخه 2.0.0: کاربران ویندوز اکنون می‌توانند از نویسه خط عمودی (|) برای اسکیپ کردن نویسه‌های خاص در فایل .stignore استفاده کنند. علاوه بر این، افزودن #escape=X به بالای فایل به کاربران امکان می‌دهد X را به عنوان نویسه اسکیپ برای آن فایل مشخص کنند.

نویسنده (AUTHOR)

نویسندگان سینک‌تینگ (The Syncthing Authors)

حق نشر (COPYRIGHT)

2014-2026, The Syncthing Authors