Налаштування журналів Beancount за допомогою директив опцій

Поведінка Beancount налаштовується директивами option, які розміщуються у верхній частині вашого основного файлу бухгалтерської книги. Ці пари ключ-значення контролюють назви кореневих рахунків, наскільки велика може бути дисбаланс у транзакції та які розширення запускаються. ⚙️

Кожна опція на цій сторінці була перевірена на Beancount 3.2.3, і кожне наведене повідомлення про помилку є тим, що друкує ця версія. Beancount відхиляє опцію, яку він не розпізнає — option "default_tolerance" "USD:0.01" помилково відкликається з Invalid option: 'default_tolerance' — тож опція, скопійована зі старішого посібника, не призведе до мовчазної помилки. Запускайте bea check на вашому файлі після будь-яких змін тут.

Основні параметри конфігурації​

Ці опції контролюють фундаментальні налаштування вашої бухгалтерської книги.

Базові налаштування​

Це одні з найпоширеніших параметрів, які ви встановите.

option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
option "plugin_processing_mode" "default"

• title: Встановлює заголовок для звітів і веб-інтерфейсів. За замовчуванням Beancount.
• render_commas: Якщо істинно, числа у звітах форматуються з тисячними роздільниками (наприклад, 1,000,000.00). За замовчуванням — хибне. Будь-яке з 1, TRUE, true, або yes читається як істина; будь-який інший рядок — як хибність.
• plugin_processing_mode: або default (за замовчуванням), або raw. Будь-яке інше значення викликає помилку Error for option 'plugin_processing_mode'.

raw — не м’якша версія default, це перемикач, який відключає власні стадії обробки Beancount. У режимі default Beancount запускає beancount.ops.documents перед плагінами, а beancount.ops.pad і beancount.ops.balance після них. У режимі raw він запускає лише плагіни, які ви вказали самі, тож директиви pad ніколи не застосовуються, а перевірки balance ніколи не виконуються:

; Under "raw" the balance stage never runs, so this obviously
; false assertion is accepted in silence.
option "plugin_processing_mode" "raw"
 
1970-01-01 open Assets:Cash
1970-01-01 open Equity:Opening-Balances
 
1970-01-02 * "Opening balance"
  Assets:Cash                100.00 USD
  Equity:Opening-Balances   -100.00 USD
 
1970-01-03 balance Assets:Cash   999.00 USD

Змініть цей рядок на default, і той самий файл повідомить Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Використовуйте raw лише якщо свідомо реалізуєте ці стадії самостійно.

Налаштування назв рахунків​

Ви можете перейменувати п’ять фундаментальних типів рахунків Beancount. Це не косметично. Опція перепризначає кореневі назви, які парсер приймає, тому кожен рахунок у вашому файлі має використовувати нову назву, а стара стає недійсною.

option "name_assets" "Actifs"
option "name_expenses" "Depenses"
 
2024-01-01 open Actifs:Banque:Courant
2024-01-01 open Depenses:Alimentation
 
2024-01-02 * "Boulangerie" "Pain"
  Depenses:Alimentation      4.20 EUR
  Actifs:Banque:Courant     -4.20 EUR

Залишене одне проведення зі старим коренем призведе до неможливості завантаження файлу з повідомленням Invalid account name: Assets:Banque:Courant. П’ять опцій — це name_assets, name_liabilities, name_equity, name_income та name_expenses; кожне значення має бути одним словом з великої літери без двокрапки, інакше виникає помилка Error for option 'name_assets': Invalid root account name. Перейменовуйте корені на початку ведення книги, а не посередині.

Конфігурація рахунку капіталу (власного капіталу)​

Beancount синтезує декілька рахунків капіталу при підсумовуванні періоду — початкові баланси, нерозподілений прибуток та конверсії валют. Ці опції задають їхні назви.

Кожне значення — це ім'я листа, і Beancount поєднує його під name_equity для вас. Записування кореня капіталу власноруч дає Equity:Equity:Opening-Balances — це вже інший рахунок, ніж той, який ви хотіли.

option "account_previous_balances" "Opening-Balances"
option "account_previous_earnings" "Earnings:Previous"
option "account_current_earnings" "Earnings:Current"
option "account_previous_conversions" "Conversions:Previous"
option "account_current_conversions" "Conversions:Current"
option "account_rounding" "Equity:Rounding"

Вийнятком у цій групі є account_rounding: ця опція приймає повну назву рахунку і зберігається точно як записано, тому Equity:Rounding в наведеному прикладі є правильним і не має подвоєного префікса. Вона також не встановлена за замовчуванням, і в Beancount 3.2.3 її встановлення не впливає на завантаження — див. Точність і допуски для того, що насправді відбувається із залишками.

Налаштування Точності та Допусків​

Ці опції контролюють, який дисбаланс Beancount приймає у транзакції.

Конфігурація стандартного допуску​

Beancount виводить допуск для кожної транзакції, ґрунтуючись на кількості десяткових знаків у проводках. Ці три опції налаштовують це виведення.

option "inferred_tolerance_default" "USD:0.01"
option "tolerance_multiplier" "1.2"
option "infer_tolerance_from_cost" "TRUE"

• inferred_tolerance_default: мінімальний допуск на валюту, використовується, коли в транзакції немає десяткових знаків для виведення. Синтаксис: <валюта>:<число>, * задає всім валютам одночасно. Опцію можна повторювати для кількох валют.
• tolerance_multiplier: частка найменшої цифри, що вважається припустимою, за замовчуванням 0.5. Це не відсоткове збільшення: 1.2 подвоює кожен виведений допуск у 2,4 рази від стандартного.
• infer_tolerance_from_cost: якщо істинно, проводки за собівартістю розширюють допуск у валюті собівартості також. За замовчуванням вимкнено.

Стара назва inferred_tolerance_multiplier все ще задає те ж значення, але викликає помилку завантаження із повідомленням Renamed to 'tolerance_multiplier'., тому bea check не проходить з файлом, який її використовує. Переіменуйте.

Метод бронювання (booking method)​

Ця опція задає правило за замовчуванням для вибору лота, з якого списується зменшення. Для одного рахунку можна задати окреме правило в директиві open.

; The file-wide default. An open directive overrides it per account.
option "booking_method" "STRICT"

Beancount 3.2.3 приймає рівно сім назв: STRICT (за замовчуванням), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO і AVERAGE. Будь-яке інше значення відхиляється при завантаженні з помилкою Error for option 'booking_method' — це включає SIMPLE і FULL, які не є методами бронювання і ніколи ними не були. AVERAGE приймається, але не реалізований; спроба зробити списання цим методом викликає помилку AVERAGE method is not supported. Управління запасами працює зі всіма сімома на одній книзі.

Валютне управління​

Правильна конфігурація валют надзвичайно важлива для точних звітів.

Оперативна валюта​

Оперативна валюта — це валюта, у якій ви хочете підсумовувати звіти. Опція повторюється для оголошення кількох валют; значення накопичуються, а не замінюють одне одного.

option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"

Оголошення оперативних валют інструктує звітні інструменти формувати для кожної власну колонку. conversion_currency дає ім'я уявній валюті, в якій Beancount веде облік конверсій за курсом нуль; за замовчуванням це NOTHING, і єдина причина змінити її — вибрати інший заповнювач, який у вашій книзі ніколи не використовується як реальний товар.

Управління документами​

Beancount може пов'язувати транзакції з зовнішніми файлами, як чек або накладна. Опція documents задає папку для сканування.

option "documents" "/home/user/Documents/beancount"

Шлях у цьому блоці ілюстративний — замініть його на свій перед запуском. Тільки перше правило нижче викликає повідомлення про помилку; порушення інших призводить лише до того, що файл не знаходиться:

• Папка має існувати. Відсутність викликає помилку Document root '/no/such/place' does not exist.
• Підпапки — це назви рахунків. Виписка для Assets:US:BofA:Checking має бути в <root>/Assets/US/BofA/Checking/. Файли, що лежать безпосередньо в корені, ігноруються.
• Рахунок має бути відкритий. Документи, знайдені під рахунком, який не відкривається у вашій книзі, ігноруються без попередження.
• Імена файлів починаються з дати у форматі YYYY-MM-DD.description.ext (наприклад, 2025-07-28.amazon-order.pdf). Все інше в папці ігнорується.
• Шляхи можуть бути абсолютними або відносними до основного файлу книги; опцію можна повторювати для кількох папок.

Система плагінів​

Функціональність Beancount можна розширювати за допомогою плагінів.

Конфігурація плагінів​

Плагін завантажується окремою директивою plugin, а не option. option "plugin" "..." викликає помилку Option 'plugin' may not be set.

plugin "beancount.plugins.auto_accounts"
 
2024-03-01 * "Coffee Shop" "Flat white"
  Expenses:Food:Coffee        4.50 USD
  Assets:US:BofA:Checking    -4.50 USD

Файл завантажується, бо auto_accounts відкриває обидва рахунки для вас; видаліть рядок plugin, і він скаже Invalid reference to unknown account 'Expenses:Food:Coffee'. Плагін, який приймає конфігурацію, отримує її як другий рядок, plugin "module" "config". Плагіни виконуються в порядку, в якому ви їх вказали, після власної стадії documents Beancount і перед pad та balance, якщо не встановлено plugin_processing_mode у raw, що відміняє ці стадії зовсім.

Технічні обмеження та ліміти​

Ці опції контролюють технічні аспекти парсера Beancount.

Обробка рядків​

Ви можете встановити обмеження на кількість рядків у багаторядковому рядку, щоб незавершена лапка викликала повідомлення про помилку ближче до того місця, де ви її ввели, а не в кінці файлу.

option "long_string_maxlines" "64"

Точність інтерполяції​

За замовчуванням Beancount використовує один допуск для двох різних цілей: заповнення відсутньої суми і визначення, чи збалансована транзакція. Увімкнення цієї опції використовує найточніший виведений допуск для першої задачі і найвільніший для другої, що запобігає дрейфу інтерпольованих сум.

option "use_precise_interpolation" "TRUE"

Опції для явних допусків на проводку немає. Єдиний явний синтаксис допусків у Beancount 3.2.3 — це тильда у директиві balance — 4.271 ~ 0.01 RGAGX — і вона не потребує опції. Тильда у середині проводки — синтаксична помилка.

Заборонені та видалені опції​

Три опції, які все ще рекомендують старі посібники, відсутні в Beancount 3.2.3. Кожен рядок із цього блоку викликає помилку завантаження:

option "experiment_explicit_tolerances" "True"
option "use_legacy_fixed_tolerances" "True"
option "default_tolerance" "USD:0.001"

• experiment_explicit_tolerances — синтаксис ~ на рівні проводки, який він включав, зник; використовуйте тильду директиви balance.
• use_legacy_fixed_tolerances — фіксовані допуски 0.005/0.015 зникли; допуск визначається для кожної транзакції та настроюється tolerance_multiplier та inferred_tolerance_default.
• default_tolerance — замінена на inferred_tolerance_default для балансування і display_precision для виводу.

Ще три досі працюють, але виводять помилку застарілості, чого достатньо для провалу bea check:

• inferred_tolerance_multiplier — перейменована на tolerance_multiplier.
• allow_pipe_separator — підтримує старий роздільник | між отримувачем і описом.
• allow_deprecated_none_for_tags_and_links — підтримує буквальний None там, де мають бути теги і посилання.

Опції Fava є окремими​

Усе на цій сторінці читається самим Beancount. Налаштування Fava не є директивами option — це директиви custom "fava-option" з датою, і Beancount їх ігнорує. Запис опції Fava як option викликає помилку Invalid option. Див. Опції Fava для списку.

Рекомендована конфігурація ✅​

Для більшості користувачів наведена нижче конфігурація забезпечує надійну та розумну стартову точку. Це один файл, і він завантажується.

; Reporting
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
 
; Precision: a floor for currencies with no decimals to infer from,
; and the default 0.5 multiplier left alone.
option "inferred_tolerance_default" "USD:0.005"
 
; Booking: identify the lot you are selling, explicitly.
option "booking_method" "STRICT"
 
; Equity account names are leaves under Equity:.
option "account_previous_balances" "Opening-Balances"
option "account_current_earnings" "Earnings:Current"

Коментарі починаються з ;. Коментар // — це синтаксична помилка в Beancount, яка відміняє весь файл.

Ця конфігурація забезпечує надійну основу для нової бухгалтерської книги Beancount, гарантуючи зрозумілі звіти, розумний контроль точності та логічну структуру рахунків капіталу.