.TH BUPSTASH-LIST 1 "2026-09-01" "bupstash" "User Commands"
.SH "نام (NAME)"
bupstash-list \- جستجو و فهرستکردن اسنپشاتهای موجود در مخزن
.SH "خلاصه دستور (SYNOPSIS)"
فهرست کردن آیتم‌ها در یک مخزن bupstash\.
.P
\fBbupstash list\fR [\fIگزینه‌ها\fR] \fIپرس‌وجو\fR\|\.\|\.\|\.
.SH "توضیحات (DESCRIPTION)"
دستور
\fBbupstash list\fR
متاداده‌های آیتم‌های ذخیره‌شده در مخزن bupstash را واکشی، رمزگشایی و چاپ می‌کند\. این دستور می‌تواند برای جستجو در پایگاه‌داده با زبان پرس‌وجوی bupstash استفاده شود\.
.P
برای فهرست‌کردن آیتم‌ها، تنها رمزگشایی متاداده‌ها لازم است؛ بنابراین یک کلید متاداده حتی بدون دسترسی به کلید رمزگشایی داده‌ها برای پرس‌وجوی آیتم‌ها کافی خواهد بود\.
.SH "زبان پرس‌وجو (QUERY LANGUAGE)"
برای مستندات کامل درباره زبان پرس‌وجو، به
.BR bupstash\-query\-language (7)
مراجعه کنید\.
.SS "مثال‌های پرس‌وجوی فهرست:"
.nf
$ bupstash list name='*\.tar'
\|\.\|\.\|\.
$ bupstash list timestamp='2020*'
\|\.\|\.\|\.
.fi
.SH "برچسب‌های ویژه (SPECIAL TAGS)"
ابزار Bupstash به طور خودکار برچسب‌های ویژه‌ای را درج می‌کند که می‌توان آن‌ها را مشاهده کرد و روی آن‌ها پرس‌وجو انجام داد؛ این برچسب‌ها در زیر تشریح شده‌اند\.
.SS "decryption\-key\-id"
این برچسب ویژه هنگامی درج می‌شود که گزینه
\fB\-\-query\-encrypted\fR
استفاده شده باشد؛ این ویژگی امکان جستجو بر اساس شناسه کلیدی را فراهم می‌سازد که برای رمزگشایی آیتم داده‌شده استفاده خواهد شد\. این برچسب بیش از همه برای هرس کردن و حذف پشتیبان‌هایی کاربرد دارد که کلید رمزگشایی آن‌ها را در اختیار ندارید\.
.SS "size"
این برچسب اندازه جریان داده و هرگونه متاداده نمایه‌ای مرتبط با اسنپ‌شات را نشان می‌دهد\. این بدان معناست که در مورد اسنپ‌شات‌ها، اندازه ممکن است دقیقاً با اندازه جریان داده بازیابی‌شده توسط
.BR bupstash\-get (1)
مطابقت نداشته باشد\.
.SS "timestamp"
زمان ایجاد آیتم با قالب
\fBYYYY/MM/DD HH:MM:SS\fR\.
.SH "حافظه موقت پرس‌وجو (QUERY CACHING)"
از آنجا که تمام داده‌ها به صورت رمزگذاری‌شده در کارساز (سرور) ذخیره می‌شوند، متاداده‌های آیتم‌ها ابتدا باید با ماشین محلی همگام‌سازی شوند و سپس جهت اجرای یک پرس‌وجو، در سمت کلاینت رمزگشایی گردند\. به فایلی که حاوی متاداده‌های همگام‌شده و رمزگذاری‌شده است، حافظه موقت پرس‌وجو (query cache) گفته می‌شود\.
.P
مسیر فایل حافظه موقت پرس‌وجو (query-cache)، در صورت تنظیم بودن متغیرهای محیطی مربوطه، به ترتیب اولویت پیش‌فرض یکی از مقادیر زیر است:
\fB$BUPSTASH_QUERY_CACHE\fR
یا
\fB$XDG_CACHE_HOME/\.cache/bupstash/bupstash\.qcache\fR
یا
\fB$HOME/\.cache/bupstash/bupstash\.qcache\fR\.
.P
به عنوان یک حالت خاص، پرس‌وجویی که تنها از یک شناسه کاملاً مشخص تشکیل شده باشد (مانند
\fBid=$FULL_ID\fR)
نیازی به استفاده از حافظه موقت پرس‌وجو نخواهد داشت و در عوض پرس‌وجو می‌تواند مستقیماً به کارساز ارسال شود\. این بدان معناست که هنگام اجرای هر دستوری که انتظار یک پرس‌وجو را دارد، مشخص‌کردن کامل یک شناسه همیشه کارآمدتر خواهد بود\.
.SH "قالب‌های خروجی (OUTPUT FORMATS)"
.SS "Human"
هنگامی که
\fB\-\-format\fR
روی
\fBhuman\fR
تنظیم شده باشد،
\fBbupstash list\fR
سطرهایی شامل موارد زیر خروجی می‌دهد:
.IP "" 4
.nf
KEY=VALUE KEY=VALUE KEY=VALUE \|\.\|\.\|\.\.
.fi
.IP "" 0
.P
که در آن هر کلید و مقدار متناظر با برچسبی است که می‌توان روی آن جستجو انجام داد\.
.SS "JSONl1"
هنگامی که
\fB\-\-format\fR
روی
\fBjsonl1\fR
تنظیم شده باشد،
\fBbupstash list\fR
در هر سطر یک شیء JSON خروجی می‌دهد\.
.P
هر سطر دارای طرح‌واره (schema) جیسون زیر است:
.IP "" 4
.nf
{
  "id": hexstring,
  "decryption_key_id": hexstring,
  "data_tree": {
    "address": hexstring,
    "height": number,
    "data_chunk_count": number
  },
  "index_tree": {
    "address": hexstring,
    "height": number,
    "data_chunk_count": number
  },
  "data_size": number, // If decryption key present\.
  "index_size": number,  // If decryption key present\.
  "put_key_id": hexstring,  // If decryption key present\.
  "data_hash_key_part": hexstring,  // If decryption key present\.
  "index_hash_key_part": hexstring,  // If decryption key present\.
  "unix_timestamp_millis": number,
  "tags": {
    string : string,
    \|\.\|\.\|\.
}
.fi
.IP "" 0
.P
اگر
\fB\-\-query\-encrypted\fR
مشخص شده باشد، برچسب‌ها و متاداده‌های رمزگذاری‌شده حذف می‌شوند\.
.SH "گزینه‌ها (OPTIONS)"
.TP
.BR \-r ", " \-\-repository " \fIREPO\fR"
مخزنی که باید به آن متصل شد؛ در صورت پیکربندی دسترسی ssh برای مخازن دوردست، می‌تواند به شکل
\fBssh://$SERVER/$PATH\fR
باشد\. در صورت عدم تعیین، از مقدار متغیر
\fBBUPSTASH_REPOSITORY\fR
استفاده می‌شود\.
.TP
.BR \-k ", " \-\-key " \fIKEY\fR"
کلید اصلی مورد استفاده برای رمزگشایی داده‌ها و متاداده‌ها\. در صورت تنظیم نشدن، مقدار پیش‌فرض آن
\fBBUPSTASH_KEY\fR
است\.
.TP
.B \-\-query\-encrypted
پرس‌وجو هیچ متاداده‌ای را رمزگشایی نمی‌کند و به شما امکان می‌دهد آیتم‌هایی را فهرست کنید که کلید رمزگشایی آن‌ها را در اختیار ندارید\. این گزینه برچسب پرس‌وجوی ساختگی 'decryption\-key\-id' را درج می‌کند\.
.TP
.BI \-\-query\-cache " PATH"
مسیر فایل حافظه موقت پرس‌وجو (query-cache)؛ در صورت تنظیم بودن متغیرهای محیطی مربوطه، به ترتیب اولویت پیش‌فرض یکی از مقادیر زیر است:
\fB$BUPSTASH_QUERY_CACHE\fR
یا
\fB$XDG_CACHE_HOME/\.cache/bupstash/bupstash\.qcache\fR
یا
\fB$HOME/\.cache/bupstash/bupstash\.qcache\fR\.
.TP
.BI \-\-format " FORMAT"
تنظیم قالب خروجی به یکی از موارد 'human' یا 'jsonl'\.
.TP
.B \-\-utc\-timestamps
نمایش و جستجو بر اساس برچسب‌های زمانی به وقت جهانی (UTC) به جای زمان محلی\.
.TP
.B \-\-no\-progress
غیرفعال‌سازی نشانگرهای پیشرفت (اگر stderr یک ترمینال تعاملی نباشد نیز نشانگرهای پیشرفت غیرفعال می‌شوند)\.
.TP
.BR \-q ", " \-\-quiet
اجرای بی‌صدا؛ متضمن
.B \-\-no\-progress
است\.
.SH "محیط (ENVIRONMENT)"
.TP
.B BUPSTASH_REPOSITORY
مخزنی که باید به آن متصل شد\. در صورت پیکربندی دسترسی ssh می‌تواند برای مخازن دوردست به شکل
\fBssh://$SERVER/$PATH\fR
باشد\.
.TP
.B BUPSTASH_REPOSITORY_COMMAND
دستوری برای اجرا جهت اتصال به یک نمونه از
.BR bupstash\-serve (1)\.
این متغیر اتصالات پیچیده‌تری را به مخزن برای کاربردهای خاص فراهم می‌کند\.
.TP
.B BUPSTASH_KEY
مسیر کلید اصلی که برای رمزگشایی داده‌ها و متاداده‌ها استفاده خواهد شد\.
.TP
.B BUPSTASH_KEY_COMMAND
دستوری برای اجرا که باید داده‌های کلید را در خروجی چاپ کند؛ می‌تواند به جای
.B BUPSTASH_KEY
برای واکشی کلید از مکان‌های دلخواه مانند شبکه یا سایر فضاهای ذخیره‌سازی محرمانه به کار رود\.
.TP
.B BUPSTASH_QUERY_CACHE
مسیر فایل حافظه موقت پرس‌وجو (query cache) جهت استفاده\.
.SH "مثال‌ها (EXAMPLES)"
.SS "فهرست کردن آیتم‌های منطبق با یک پرس‌وجو"
.nf
$ bupstash list name=backup\.tar and timestamp=2020/07/*
id="aa87fdbc72241f363568bbb888c0834e" name="backup\.tar" size="106\.34MB" timestamp="2020\-07\-24 15:25:00"
id="d271ec0b989cfc20e10d01380115747e" name="backup\.tar" size="146\.38MB" timestamp="2020\-07\-29 15:25:24"
\|\.\|\.\|\.
.fi
.SH "همچنین ببینید (SEE ALSO)"
.BR bupstash (1),
.BR bupstash\-list\-contents (1),
.BR bupstash\-keyfiles (7),
.BR bupstash\-query\-language (7)