TODO(1) Todoman TODO(1)

todo - یک مدیر وظایف خط فرمانی، ساده و مبتنی بر استانداردها

کاربرد

todo [OPTIONS] COMMAND [ARGS]...

گزینه‌ها

یکی از مقادیر CRITICAL، ERROR، WARNING، INFO یا DEBUG
به‌طور پیش‌فرض، اگر stdout یک TTY نباشد، todoman خروجی رنگی را غیرفعال می‌کند (مقدار auto). برای غیرفعال کردن کامل خروجی رنگی آن را روی never تنظیم کنید، یا برای فعال‌سازی آن در هر شرایطی روی always قرار دهید.
گزینه‌ها
always | auto | never
استفاده از یک ساختار JSON که صرف‌نظر از پیکربندی یا نسخه، پایدار باقی می‌ماند.
قالب‌بندی تمام تاریخ‌ها و زمان‌ها به شیوه‌ای خوانا برای انسان
فایل پیکربندی مورد استفاده.
نمایش نسخه و خروج.

متغیرهای محیطی

تعیین مقدار پیش‌فرض برای --config

دستورها

لغو یک یا چند وظیفه.
رونوشت وظایف به فهرستی دیگر.
حذف وظایف.
علامت‌گذاری یک یا چند وظیفه به عنوان انجام‌شده.
ویرایش وظیفه با شناسه ID.
حذف وظایف انجام‌شده.
فهرست کردن وظایف (پیش‌فرض).
بازگرداندن تمام فهرست‌ها
انتقال وظایف به فهرستی دیگر.
ایجاد یک وظیفه جدید با SUMMARY.
چاپ مسیر فایل مربوط به یک وظیفه.
راه‌اندازی یک پوسته تعاملی.
نمایش جزئیات درباره یک وظیفه.

برنامه Todoman یک ابزار مدیریت کارهای انجام‌دادنی (یا به بیانی دیگر: وظایف) ساده، مبتنی بر استانداردها و خط فرمانی (cli) است. کارهای انجام‌دادنی در فایل‌های icalendar ذخیره می‌شوند، به این معنی که می‌توانید آن‌ها را از طریق CalDAV با استفاده از ابزارهایی مانند vdirsyncer همگام‌سازی کنید.

استفاده از Todoman مبتنی بر خط فرمان (CLI) https://en.wikipedia.org/wiki/Command-line_interface است (هرچند بخش‌هایی بر پایه TUI دارد و هدف این است که یک رابط کاربری کاملاً مبتنی بر TUI https://en.wikipedia.org/wiki/Text-based_user_interface نیز ارائه شود).

عمل پیش‌فرض list است که تمام وظایف را برای همه تقویم‌ها نمایش می‌دهد، هر کدام همراه با یک شناسه (id) یکتای نیمه‌پایدار:

1 [ ] !!! 2015-04-30 Close bank account @work (0%)
2 [ ] !              Send minipimer back for warranty replacement @home (0%)
3 [X]     2015-03-29 Buy soy milk @home (100%)
4 [ ] !!             Fix the iPad's screen @home (0%)
5 [ ] !!             Fix the Touchpad battery @work (0%)

ستون‌ها به ترتیب عبارتند از:

  • یک شناسه (id).
  • اینکه آیا وظیفه تکمیل شده است یا خیر.
  • علامت !!! نشان‌دهنده اولویت بالا، !! اولویت متوسط، و ! نشان‌دهنده وظایف با اولویت پایین.
  • تاریخ سررسید (due date).
  • خلاصه وظیفه.
  • فهرستی که وظیفه به آن تعلق دارد؛ هنگام فیلتر کردن بر اساس یک فهرست یا زمانی که پایگاه‌داده تنها شامل یک فهرست باشد، پنهان خواهد شد.
  • درصد تکمیل‌شده.

شناسه تا اجرای بعدی دستور flush توسط todoman نگه‌داری می‌شود.

برای انجام عملیات روی یک مورد todo، از شناسه برای ارجاع به آن استفاده می‌شود. برای نمونه، جهت ویرایش وظیفه Buy soy milk از مثال بالا، دستور مناسب todo edit 3 است، یا todo undo 3 برای لغو علامت‌گذاری وظیفه به عنوان انجام‌شده.

ویرایش وظایف در حال حاضر تنها از طریق رابط کاربری TUI امکان‌پذیر است و هنوز نمی‌توان آن را از طریق خط فرمان انجام داد.

اگر می‌خواهید وظایف خود را همگام‌سازی کنید، به ابزاری نیاز خواهید داشت که از طریق CalDAV همگام‌سازی کند. ابزار vdirsyncer https://vdirsyncer.readthedocs.org/en/stable برای این منظور پیشنهاد می‌شود.

اگر click-repl https://github.com/untitaker/click-repl نصب باشد، todoman از دستور repl پشتیبانی می‌کند که یک پوسته تعاملی با قابلیت تکمیل خودکار کلید Tab را اجرا می‌نماید.

هنگام تلاش برای ادغام todoman در سامانه‌های دیگر یا تجزیه خروجی آن، توصیه می‌شود از پرچم --porcelain استفاده کنید که تمام خروجی را در قالبی از پیش تعریف‌شده چاپ می‌کند که فارغ از پیکربندی کاربر یا نسخه برنامه ثابت و پایدار خواهد ماند.

قالب داده JSON است، شامل یک آرایه واحد که هر todo را به عنوان یک ورودی (شیء) مجزا در بر دارد. فیلدها همیشه وجود خواهند داشت؛ اگر یک todo مقداری برای یک فیلد مشخص نداشته باشد، به صورت null چاپ خواهد شد.

ممکن است در آینده فیلدهایی اضافه شوند، اما هرگز هیچ فیلدی حذف نخواهد شد.

برنامه Todoman را می‌توان با استفاده از یکی از متغیرهای اجرای پوسته https://conky.sourceforge.net/variables.html همراه با Conky https://conky.cc استفاده کرد. با توجه به ماهیت ابزارهای pimutils، نیازی نیست در هر بار به‌روزرسانی conky اطلاعات جدید استعلام شود، بنابراین در بیشتر مواقع execi بهترین گزینه خواهد بود.

افزودن ${execi 30 todo} در بخش متن (text)، خروجی دستور را نمایش داده و آن را هر ۳۰ ثانیه یک‌بار به‌روزرسانی می‌کند.

یک پیکربندی کاربردی را می‌توانید در اینجا بیابید: https://github.com/r4ulill0/todoman/blob/main/docs/examples/conky.conf..SH "مرتب‌سازی (SORTING)"

مأموریت‌ها را می‌توان با آرگومان --sort مرتب‌سازی کرد. مرتب‌سازی ممکن است بر اساس فیلدهای زیر انجام گیرد:

  • description
  • location
  • status
  • summary
  • uid
  • rrule
  • percent_complete
  • priority
  • sequence
  • categories
  • completed_at
  • created_at
  • dtstamp
  • start
  • due
  • last_modified

می‌توان یک علامت - را پیش از نام فیلد اضافه کرد تا مرتب‌سازی بر اساس آن فیلد به صورت صعودی انجام شود (به‌صورت پیش‌فرض مرتب‌سازی به صورت نزولی است).

مثال:

todo list --sort due,-priority

پیش از نخستین استفاده، لازم است Todoman را با استفاده از فایل پیکربندی سادهٔ شبیه به ini آن پیکربندی کنید.

فایل پیکربندی باید در مسیر $XDG_CONFIG_HOME/todoman/config.py قرار گیرد. $XDG_CONFIG_HOME در اکثر شرایط به‌طور پیش‌فرض برابر با ~/.config است، بنابراین این مسیر عموماً ~/.config/todoman/config.py خواهد بود.

محل قرارگیری فایل کَش (یک پایگاه دادهٔ sqlite). از این فایل برای ذخیرهٔ داده‌های todo و افزایش سرعت اجرا/راه‌اندازی استفاده می‌شود و همچنین شامل شناسه‌های (ID) todoها است. اگر این مقدار مشخص نشود، مسیری نسبی نسبت به $XDG_CACHE_HOME استفاده خواهد شد. $XDG_CACHE_HOME عموماً به ~/.cache/ اشاره دارد.
نوع
str
پیش‌فرض
"$XDG_CACHE_HOME/todoman/cache.sqlite3"
به‌طور پیش‌فرض، اگر خروجی استاندارد (stdout) یک TTY نباشد، todoman خروجی رنگی را غیرفعال می‌کند (مقدار auto). مقدار را روی never تنظیم کنید تا خروجی رنگی به‌طور کامل غیرفعال شود، یا روی always قرار دهید تا در هر حالتی فعال باشد. این مقدار را می‌توان با گزینهٔ --color بازنویسی کرد.
نوع
str
پیش‌فرض
"auto"
قالب تاریخ که هم برای نمایش تاریخ‌ها و هم برای تجزیهٔ تاریخ‌های ورودی به کار می‌رود. اگر این گزینه مشخص نشود، از قالب لوکال (locale) سیستم استفاده خواهد شد.
نوع
str
پیش‌فرض
"%x"
دستوری که هنگام اجرای todo بدون هیچ زیردستوری اجرا می‌شود.
نوع
str
پیش‌فرض
"list"
اختلاف زمانی پیش‌فرض (به ساعت) میان تاریخ سررسید todo جدید و تاریخ ایجاد آن. اگر مشخص نشود، مقدار آن 24 است. اگر روی 0 تنظیم شود، تاریخ سررسید برای todoهای جدید تعیین نخواهد شد.
نوع
int
پیش‌فرض
24
لیست پیش‌فرض برای افزودن todo. اگر این گزینه را مشخص نکنید، باید هربار که یک todo اضافه می‌کنید از گزینهٔ --list / -l استفاده نمایید.
نوع
str
پیش‌فرض
None
اولویت پیش‌فرض مأموریت هنگام ایجاد. بالاترین اولویت 1، پایین‌ترین اولویت 10 است، و 0 به معنای نداشتن هیچ‌گونه اولویتی است.
نوع int
پیش‌فرض
None
رشته‌ای که برای جداسازی تاریخ و زمان هنگام نمایش و تجزیه استفاده می‌شود.
نوع
str
پیش‌فرض
" "
اگر روی true تنظیم شود، تاریخ و زمان‌ها در قالب‌های انسان‌فهم مانند "tomorrow"، "in one hour"، "3 weeks ago" و غیره چاپ خواهند شد.

اگر false باشد، تاریخ و زمان‌ها با استفاده از date_format و time_format قالب‌بندی خواهند شد.

نوع
bool
پیش‌فرض
False
یک الگوی glob که با دایرکتوری‌های محل قرارگیری وظایف (todos) شما تطبیق می‌یابد. این الگو بسط داده خواهد شد و با هر دایرکتوری منطبق (شامل هرگونه فایل icalendar) به‌عنوان یک فهرست رفتار می‌شود.
نوع
str
پیش‌فرض
"~/calendars/"
اگر روی true تنظیم شود، فقط وظایفی نمایش داده می‌شوند که در حال حاضر قابل شروع باشند؛ این‌ها وظایفی هستند که تاریخ شروع آن‌ها امروز یا روزی در گذشته است. وظایف بدون تاریخ شروع همیشه جاری در نظر گرفته می‌شوند. وظایف ناتمام (برای مثال: partially-complete) نیز لحاظ می‌شوند.
نوع
bool
پیش‌فرض
False
قالب تاریخی که هم برای نمایش زمان‌ها و هم برای تجزیه زمان‌های ورودی استفاده می‌شود.
نوع
str
پیش‌فرض
"%X"

مثال زیر می‌تواند به عنوان مرجع استفاده شود. این نمونه فایل‌های ics را از هر دایرکتوری درون ~/.local/share/calendars/ می‌خواند، از قالب تاریخ ISO-8601 استفاده می‌کند، و موعد سررسید کارهای جدید را روی ۴۸ ساعت بعد تنظیم می‌نماید.

# A glob expression which matches all directories relevant.
path = "~/my_calendars/*"
date_format = "%Y-%m-%d"
time_format = "%H:%M"
default_list = "Personal"
default_due = 48

  • می‌توانید با ایجاد یک فایل color حاوی کد رنگ در قالب هگزادسیمال (#RRGGBB)، برای هر فهرست کارها یک رنگ تنظیم کنید.
  • فایلی با نام displayname مشخص می‌کند که فهرست کارها چگونه باید نام‌گذاری شود و زمانی که چندین دایرکتوری با نام مشترک وجود دارند (به عنوان مثال هنگام استفاده از چندین $CloudInstances)، لازم است. پیش‌فرض، نام دایرکتوری است.

همچنین مستندات مرتبط با قالب vdir را ببینید: https://vdirsyncer.pimutils.org/en/stable/vdir.html#metadata.

برنامه Todoman از منطقه زمانی پیکربندی‌شده در سطح سیستم استفاده خواهد کرد. اگر این تنظیم برای شما مناسب نیست، _می‌توانید_ با تعیین متغیر محیطی TZ، منطقه زمانی را بازنویسی کنید.

برای دریافت دستورالعمل‌های تغییر منطقه زمانی سیستم خود، به مستندات توزیع‌تان مراجعه کنید.

پشتیبانی از مشخصه percent-completed ناقص است. برنامه Todoman فقط می‌تواند کارها را به عنوان انجام‌شده (۱۰۰٪) علامت‌گذاری کند، و مقادیر مربوط به percent > 0 ^ percent < 100 را نه منعکس می‌کند و نه اجازه ویرایش آن‌ها را می‌دهد.

برای اطلاعات در مورد نحوه مشارکت، ببینید: https://todoman.readthedocs.io/en/stable/contributing.html

برنامه Todoman تحت پروانه ISC منتشر شده است. برای جزئیات، LICENCE را ببینید.

Hugo Osvaldo Barrera <hugo@whynothugo.nl>، و دیگران

2015-2023, Hugo Osvaldo Barrera

April 22, 2026 4.7.0