www.dntips.ir
مطالب ۳۶۹۴
نویسندگان ۲۷۶
گروه‌های مطالب ۱۰۲۴
نقشه‌های راه ۱۱۹
دوره‌ها ۱۴
اشتراک‌ها ۱۷۹۱۴
عنوان:

‫راهنمای رفع خطای طولانی بودن مسیر فایل‌ها (Filename too long) در ویندوز و گیت


نویسنده: وحید نصیری
تاریخ: ۱۴۰۵/۰۴/۱۹ ۰۹:۲۰
آدرس: www.dntips.ir
بسیاری از توسعه‌دهندگان در محیط ویندوز هنگام کار با مخازن بزرگ گیت (Git) با خطای ناامیدکننده‌ای مواجه شده‌اند. این خطا معمولاً زمانی رخ می‌دهد که قصد دارید یک پروژه بزرگ را کلون (Clone) کنید یا شاخه‌ای جدید را بیرون بکشید (Checkout). گیت پیغامی مشابه زیر را نمایش می‌دهد:
error: unable to create file some/very/deeply/nested/path/to/a/file.ts: Filename too long
نکته مهم این است که کدهای شما یا ساختار مخزن هیچ مشکلی ندارند؛ بلکه این یک محدودیت قدیمی در سیستم‌عامل ویندوز است. در این مقاله علمی و کاربردی، به ریشه‌یابی این مشکل پرداخته و راهکارهای گام‌به‌گام برای حل آن در سطوح گیت و سیستم‌عامل را بررسی می‌کنیم. همچنین نکاتی اختصاصی برای توسعه‌دهندگان دات‌نت جهت مدیریت این محدودیت در برنامه‌هایشان ارائه خواهیم داد.

۱. چرا این خطا رخ می‌دهد؟ ریشه‌یابی فنی
به طور پیش‌فرض، سیستم‌عامل ویندوز از یک محدودیت تاریخی به نام MAX_PATH پیروی می‌کند که حداکثر طول مسیر یک فایل را به ۲۶۰ کاراکتر محدود می‌سازد. این ۲۶۰ کاراکتر شامل حرف درایو (مانند C:\)، پوشه‌های تودرتو، نام فایل و کاراکتر نال پایانی (Null-terminator) است.
هرچند ساختارهای مدرن توسعه نرم‌افزار (مانند پوشه node_modules در جاوااسکریپت یا ساختار فضاهای نام و پوشه‌های عمیق در پروژه‌های بزرگ دات‌نت) به راحتی این سقف را رد می‌کنند، اما گیت در ویندوز به صورت پیش‌فرض سقف مسیرهای طولانی را رعایت می‌کند تا با سیستم‌عامل سازگار بماند. بنابراین وقتی طول مسیر کامل یک فایل از ۲۶۰ کاراکتر بیشتر شود، عملیات ایجاد فایل توسط گیت با شکست مواجه خواهد شد.

۲. راهکار اول: فعال‌سازی مسیرهای طولانی در گیت (core.longpaths)
خوشبختانه گیت یک پیکربندی داخلی به نام core.longpaths دارد که به آن اجازه می‌دهد محدودیت ۲۶۰ کاراکتری را دور بزند. بسته به میزان دسترسی خود در سیستم، می‌توانید این ویژگی را به دو روش فعال کنید:
الف) فعال‌سازی در سطح کل سیستم (نیاز به دسترسی Administrator)
اگر دسترسی مدیریت سیستم را دارید، پیشنهاد می‌شود این ویژگی را به صورت سراسری برای تمامی کاربران و مخازن فعال کنید:
git config --system core.longpaths true

ب) فعال‌سازی در سطح کاربر (بدون نیاز به دسترسی Administrator)
اگر در محیط‌های سازمانی کار می‌کنید و دسترسی ادمین ندارید، می‌توانید این تغییر را صرفاً برای حساب کاربری خود اعمال کنید که برای رفع مشکل شما کاملاً کافی است:
git config --global core.longpaths true
نکته کلیدی: فعال کردن این گزینه در گیت، فقط به نرم‌افزار گیت اجازه می‌دهد که فایل‌هایی با مسیر طولانی ایجاد کند. با این حال، اگر ویندوز یا سایر ابزارهای توسعه (مانند برخی نسخه‌های قدیمی‌تر IDEها یا ابزارهای خط فرمان) با مسیرهای طولانی سازگار نباشند، ممکن است در خواندن یا پردازش این فایل‌ها دچار مشکل شوند. بنابراین، گام بعدی برای یک حل ریشه‌ای ضروری است.

۳. راهکار دوم: فعال‌سازی پشتیبانی از مسیرهای طولانی در سطح ویندوز
برای اینکه مطمئن شوید سیستم‌عامل و ابزارهای جانبی (مانند File Explorer) نیز از این فایل‌ها پشتیبانی می‌کنند، باید قابلیت Win32 Long Paths را در ویندوز فعال کنید.
روش اول: از طریق Group Policy Editor (مخصوص نسخه‌های Windows Pro & Enterprise)
  • کلیدهای Win + R را فشرده، عبارت gpedit.msc را تایپ کرده و اینتر بزنید.
  • به مسیر زیر بروید:
  • Computer Configuration > Administrative Templates > System > Filesystem
  • گزینه Enable Win32 long paths را پیدا کرده، روی آن دو بار کلیک کنید و وضعیت آن را روی Enabled قرار دهید.

روش دوم: از طریق رجیستری (مخصوص نسخه‌های Windows Home)
در صورتی که به Group Policy دسترسی ندارید، ابزار خط فرمان (CMD) را به صورت Run as Administrator باز کرده و دستور زیر را اجرا کنید:
reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f
توجه: پس از اعمال هر یک از این دو روش، سیستم خود را مجدداً راه‌اندازی (Reboot) کنید تا تغییرات در سطح هسته سیستم‌عامل اعمال شوند.

۴. نکاتی برای توسعه‌دهندگان دات‌نت و مسیرهای طولانی
به عنوان یک توسعه‌دهنده دات‌نت، دانستن نحوه رفتار پلتفرم با مسیرهای طولانی بسیار ارزشمند است و به پایداری نرم‌افزارهای تولیدی شما کمک می‌کند:
  • در NET Core. و NET 5+.: در نسخه‌های مدرن دات‌نت، پشتیبانی از مسیرهای طولانی به صورت پیش‌فرض تعبیه شده است. اگر سیستم‌عامل ویندوز شما (طبق راهکار دوم) پیکربندی شده باشد، برنامه‌های دات‌نت شما بدون هیچ مشکلی فایل‌های با مسیر طولانی را مدیریت خواهند کرد.
  • در NET Framework. (نسخه‌های 4.6.2 به بعد): اگر هنوز روی پروژه‌های قدیمی‌تر کار می‌کنید، علاوه بر فعال‌سازی در ویندوز، باید فایل app.config یا manifest برنامه خود را بروزرسانی کنید تا دات‌نت فریم‌ورک رفتارهای قدیمی خود را کنار بگذارد:
<runtime>
  <AppContextSwitchOverrides value="Switch.System.IO.UseLegacyPathHandling=false;Switch.System.IO.BlockLongPaths=false" />
</runtime>

نتیجه‌گیری
خطای Filename too long یک محدودیت قدیمی میراث سیستم‌عامل DOS در ویندوز است که امروزه به راحتی قابل برطرف شدن است. با ترکیب دو دستور ساده گیت و یک تغییر کوچک در پیکربندی ویندوز، می‌توانید پایداری فرآیند CI/CD و محیط توسعه خود را تضمین کنید. به عنوان یک توسعه‌دهنده دات‌نت، هماهنگ‌سازی زیرساخت سیستم‌عامل با نیازمندی‌های ابزارهای مدرن، از گام‌های کلیدی در مدیریت حرفه‌ای چرخه‌ی حیات نرم‌افزار است.
مطالب مشابه