Настройка журналов Beancount с помощью директив option

Поведение 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: Если true, числа в отчетах форматируются с разделителями разрядов (например, 1,000,000.00). По умолчанию — false. Любое из 1, TRUE, true или yes интерпретируется как true; любая другая строка — как false.
• 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: Минимальное значение по валюте, используемое, когда в транзакции нет знаков после запятой для вывода. Синтаксис — <currency>:<number>, а * устанавливает значение для всех валют одновременно. Повторите параметр, чтобы задать несколько.
• tolerance_multiplier: Доля наименьшей цифры, который считается допустимой, по умолчанию 0.5. Это не процентное увеличение: 1.2 делает каждую выводимую массу в 2.4 раза больше значения по умолчанию.
• infer_tolerance_from_cost: Если true, записи, выраженные по себестоимости, увеличивают допуск также в валюте стоимости. По умолчанию — отключено.

Старое имя inferred_tolerance_multiplier по-прежнему устанавливает то же значение, но при загрузке выводит ошибку Renamed to 'tolerance_multiplier'., поэтому bea check завершается с ошибкой на файле, который его использует. Переименуйте его.

Метод резервирования​

Этот параметр устанавливает правило по умолчанию для выбора лота, из которого производится уменьшение. Для одного счета дайте другое правило в его директиве open.

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

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

Управление валютами​

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

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

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

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

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

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

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

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

Путь в этом блоке — иллюстрация; подставьте свой собственный перед запуском. Правила строгие, и каждое из них — это тихий no-op, а не ошибка, если вы что-то пропустили:

• Папка должна существовать. Отсутствующая папка приводит к ошибке загрузки 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 Options для этого списка.

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

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

; 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, обеспечивая четкую отчетность, разумный контроль точности и логичную структуру счетов капитала.