---
title: "اسم فایلت می‌تونه عجیب باشه؛ ابزارهات نباید عجیب‌ترش کنن"
description: "fd --format اسم فایل‌های غیر UTF-8 را در pipe بی‌صدا تغییر می‌داد و xargs فایل را پیدا نمی‌کرد. فیکس من (sharkdp/fd PR #2197) در upstream merge شد."
author: "Mohammad Pouya Ghourchiani"
canonical: "https://ghourchiani.ir/fa/blog/fd-weird-filenames-raw-bytes"
image: "https://ghourchiani.ir/og/mark-square.png"
date: "2026-11-07"
lang: "fa"
generated: "2026-11-19"
---
# اسم فایلت می‌تونه عجیب باشه؛ ابزارهات نباید عجیب‌ترش کنن

> **خلاصه:** وقتی خروجی fd --format به pipe می‌رفت، بایت‌های نامعتبر در نام فایل‌های غیر UTF-8 با U+FFFD جایگزین می‌شدند و ابزارهایی مثل xargs -0 مسیری می‌گرفتند که روی دیسک وجود نداشت. PR #2197 روی Unix، وقتی stdout ترمینال نیست، همان بایت‌های اصلی را می‌نویسد. این PR در ۷ نوامبر ۲۰۲۶ در sharkdp/fd merge شد.

## پاسخ مستقیم

در لینوکس اسم فایل فقط یک دنباله بایت است و لازم نیست UTF-8 معتبر باشد. تا همین هفته، وقتی خروجی `fd --format '{}'` به pipe می‌رفت، اسمی مثل `test_\xFEinvalid.txt` با خروجی سالم بیرون نمی‌آمد: بایت `FE` جایش را به `EF BF BD` (کاراکتر جایگزین یونیکد، `�`) می‌داد. ابزار بعدی در pipeline، مثلاً `xargs -0 rm` یا `xargs -0 cp`، دنبال فایلی می‌گشت که **وجود نداشت**.

فیکس من، [sharkdp/fd #2197](https://github.com/sharkdp/fd/pull/2197)، روی Unix هر وقت stdout ترمینال نباشد، همان بایت‌های اصلی را می‌نویسد. این PR در upstream merge شده و در نسخهٔ بعدی fd منتشر می‌شود.

## کامپیوتری که فکر می‌کرد بهتر می‌داند 🤖

فرض کن یک فایل با اسمی کمی عجیب به کامپیوترت می‌دهی و او می‌گوید:

> «هوم، این اسم رو دوست ندارم. بذار برات درستش کنم!»

فایل rename نمی‌شود و روی دیسک دقیقاً همان است که بود. چیزی که عوض می‌شود **اسمی است که به ابزار بعدی می‌رسد**. تو آن اسم را می‌خواهی و یک نسخهٔ «تمیزشده» تحویل می‌گیری که با هیچ فایلی روی دیسک جور نیست.

نه چیزی crash می‌کند و نه خطایی log می‌شود. بعداً می‌فهمی، وقتی `xargs` می‌گوید `No such file or directory` و تو به خودت شک می‌کنی.

نرم‌افزار نباید این‌قدر سخت‌گیر باشد.

## بازتولید در ۱۰ ثانیه

این مراحل از گزارش اصلی، [sharkdp/fd #2189](https://github.com/sharkdp/fd/issues/2189)، آمده است:

```sh
mkdir t && touch "t/test_$(printf '\xfe')invalid.txt"

# plain fd: the raw byte survives
fd invalid t | xxd | head -1

# --format before the fix: FE became EF BF BD
fd --format '{}' invalid t | xxd | head -1
```

خروجی معمولی `fd` از قبل درست کار می‌کرد. فقط مسیر `--format` از `to_string_lossy()` رد می‌شد، که روش مؤدبانهٔ Rust است برای گفتن «هرچه را نفهمم جایگزین می‌کنم». حتی یک کامنت هم همان‌جا گذاشته شده بود:

```rust
// TODO: support writing raw bytes on unix?
```

کل ماجرا همین TODO است. کسی قبلاً مشکل را دیده بود و برای بعد یادداشتش کرده بود.

## فیکس: چیزی را که از تو نخواسته‌اند عوض نکن

تغییر در `src/output.rs` کوچک است. اگر روی Unix هستیم و stdout ترمینال تعاملی **نیست**، بایت‌های `OsStr` را دست‌نخورده بنویس؛ در غیر این صورت رفتار قبلی می‌ماند:

```rust
#[cfg(unix)]
{
    use std::os::unix::ffi::OsStrExt;

    if config.interactive_terminal {
        print_entry_format_base(stdout, &output, config)
    } else {
        // Preserve the original path bytes when stdout is not an interactive terminal.
        stdout.write_all(output.as_os_str().as_bytes())
    }
}
```

چرا روی ترمینال نسخهٔ lossy حفظ شد؟ چون آنجا انسان می‌خواندش. یک `�` روی صفحه صادق و خواناست، ولی بایت خام `0xFE` ممکن است ترمینال را به‌هم بریزد. آن سر pipe یک برنامه نشسته و برنامه بایت واقعی لازم دارد.

این رفتار با مسیر خروجی عادی fd یکی است، پس `--format` حالا همان کاری را می‌کند که `fd` ساده می‌کند.

## بار اصلی روی تست‌هاست

۲۲ خط کد به اندازهٔ ۵۴ خط تست اهمیت نداشت. تست `test_format_invalid_utf8` یک فایل واقعی با بایت `\xFE` در نامش می‌سازد و همهٔ placeholderها را بایت‌به‌بایت چک می‌کند:

| Placeholder | خروجی مورد انتظار |
|---|---|
| `{}` | `test1/test_\xFEinvalid.txt` |
| `{/}` | `test_\xFEinvalid.txt` |
| `{//}` | `test1` |
| `{.}` | `test1/test_\xFEinvalid` |
| `{/.}` | `test_\xFEinvalid` |
| `{}` با `--print0` | `test1/test_\xFEinvalid.txt\0` |
| `{}` با `--path-separator =` | `test1=test_\xFEinvalid.txt` |

این تست روی macOS اجرا نمی‌شود، چون APFS نام‌ها را به UTF-8 تبدیل می‌کند و اصلاً نمی‌شود آنجا فایل خراب ساخت. روی Windows هم اجرا نمی‌شود، چون آنجا مسیرها UTF-16 هستند و این مسئلهٔ دیگری است.

## چه یاد گرفتم

- **TODOها را بخوان.** بعضی از بهترین مشارکت‌های اول، از قبل به شکل یک سؤال در کد نوشته شده‌اند.
- **با `xxd` بازتولید کن، نه با چشم.** ترمینال «کمکت می‌کند» و باگ را قایم می‌کند؛ hex dump نه.
- **scope را کوچک نگه دار.** خروجی ترمینال، Windows و `--path-separator` مثل قبل رفتار می‌کنند؛ فقط حالت خراب عوض شد.
- **دربارهٔ هم‌پوشانی مؤدب باش.** نویسندهٔ issue گفته بود فیکسی آماده دارد، ولی PR لینک‌شده‌ای پیدا نکردم. پس PR خودم را باز کردم و در آن نوشتم که اگر رویکردش فرق دارد، PR خودم را به نفع او می‌بندم.
- **اعتبار را به reviewer بده.** [Thayne McCombs (@tmccombs)](https://github.com/tmccombs) PR را review کرد، کامیت نهایی را push کرد و merge کرد. وقت maintainer کمیاب‌ترین منبع اوپن‌سورس است.

## به زبان عدد

- **پروژه:** [sharkdp/fd](https://github.com/sharkdp/fd)، جایگزین سریع `find` که با Rust نوشته شده
- **PR:** [#2197: fix: write raw bytes for piped --format output on unix](https://github.com/sharkdp/fd/pull/2197)
- **issue:** [#2189](https://github.com/sharkdp/fd/issues/2189)
- **تغییرات:** ۳ فایل، ‎+78 / −2 (`src/output.rs`، `tests/tests.rs`، `CHANGELOG.md`)
- **CI:** ۲۰ چک، ۱۹ پاس و ۱ skip، بدون هیچ شکست
- **وضعیت:** merge شده در `master` در ۷ نوامبر ۲۰۲۶

بی‌گریم ناخواسته. بی‌فایل گم‌شده. بگذار اسم فایل‌ها خودشان باشند. 💖

## پرسش‌های پرتکرار

### چرا xargs برای فایلی که وجود دارد می‌گوید No such file or directory؟

معمولاً چون ابزاری قبل‌تر در pipeline بایت‌های اسم را عوض کرده است. اگر اسم فایل UTF-8 معتبر نباشد، ابزاری که آن را به متن تبدیل می‌کند ممکن است بایت خراب را با `�` عوض کند، و بعد `xargs` از کرنل اسمی را می‌خواهد که وجود ندارد. لیست را از `xxd` رد کن و با اسم واقعی مقایسه کن.

### آیا اسم فایل در لینوکس می‌تواند UTF-8 نامعتبر باشد؟

بله. برای کرنل لینوکس اسم فایل هر دنباله بایتی است به جز `/` و بایت NUL. UTF-8 یک قرارداد است، نه قانون. macOS (APFS) فرق دارد و اسم‌ها را حتماً UTF-8 معتبر می‌خواهد.

### کاراکتر � (U+FFFD) چیست؟

کاراکتر جایگزین یونیکد. نرم‌افزار آن را جایی می‌گذارد که بایتی را نتوانسته decode کند. در UTF-8 این کاراکتر سه بایت `EF BF BD` است؛ یعنی یک بایت خراب به سه بایت متفاوت تبدیل می‌شود.

### فیکس در کدام نسخهٔ fd است؟

در changelog نسخهٔ بعد از fd 10.5.1 آمده است. تا آن موقع می‌توانی fd را از `master` بسازی.

### چطور بایت‌های واقعی اسم یک فایل را ببینم؟

به جای چشم از hex dump استفاده کن: `ls | xxd` یا `fd pattern | xxd`. برای مبانی خواندن این بایت‌ها، [کد اسکی و جدول اسکی: تبدیل hex به ascii در ترمینال](/fa/blog/ascii-table-hex-to-ascii-terminal) را ببین.

## لینک‌ها

- [کد اسکی و جدول اسکی: تبدیل hex به ascii و برعکس در ترمینال](/fa/blog/ascii-table-hex-to-ascii-terminal)
- [همهٔ مشارکت‌های upstream: /fa/open-source](/fa/open-source)
- [یادداشت مشارکت upstream: Biome، Nitro، Watchexec، ripgrep](/fa/blog/upstream-contribution-diary)
- [فیکس هشدار غلط Biome برای forwardRef](/fa/blog/biome-forwardref-false-positive)
- [دربارهٔ نویسنده](/fa/about)
