Collaborative Ledger Editing: How Do You Handle Multi-User Beancount Workflows?

General
1

Hey everyone,

I’m Bob Martinez, running a small bookkeeping practice in Austin with about 20 clients. I’ve been using Beancount for the past year and absolutely love it—the plain text format, Git version control, and Fava interface have been game-changers for my business.

Here’s my challenge: My practice is growing faster than I can handle alone, and I need to bring on a junior bookkeeper to help manage the workload. This is exciting, but it’s also raising questions I’ve never had to think about before.

The Multi-User Problem

Right now, I’m the only one touching the ledger files. I have complete control and mental context over every transaction. But soon, I’ll have another person entering transactions, reconciling accounts, and working on the same client books—potentially at the same time.

Coming from a restaurant management background, I never had to think about “collaborative text file editing” before. Now I’m realizing Beancount’s strength (plain text + Git) is also a complexity I need to manage carefully.

Questions I’m Wrestling With

1. Git branching strategy: What works best for accounting teams?

  • Should we use feature branches per client?
  • Per time period (monthly)?
  • Per bookkeeper?
  • Something else entirely?

2. Merge conflicts: How do you handle situations where two people edit the same date range or account?

  • In code, merge conflicts are annoying but manageable
  • In accounting, merge conflicts could mean duplicated transactions or missed entries
  • Are there safeguards or workflows that prevent this?

3. Review process: Before changes hit the “production” books, how do you review?

  • Pull requests with manual review?
  • Automated validation (balance assertions)?
  • Both?

4. Real-time vs async: Should we be using Git’s async workflow, or is there a better way?

  • I know Beancount.io v3 added some collaboration features in 2025
  • Has anyone tried that versus traditional Git workflows?

My Current Thinking

I’m leaning toward something like:

  • Each bookkeeper works on a feature branch when entering monthly transactions
  • Branch naming: 2026-03-bob-client-acme and 2026-03-sarah-client-widgetco
  • Review each other’s work via pull requests before merging to main
  • Main branch stays protected and always balanced

But honestly, I’m not sure if that’s overkill, too simple, or just wrong for accounting workflows.

The Ask

For those of you working in teams with Beancount:

  • What Git workflow do you use?
  • How do you prevent stepping on each other’s toes?
  • What lessons did you learn the hard way?
  • Any tools or scripts that make collaboration smoother?

I want to set up good habits from day one rather than scrambling to fix problems later. Any advice from the community would be hugely appreciated!

Thanks in advance,
Bob

2

Hey Bob! Congrats on the growth - this is exactly the kind of “good problem to have” situation!

I’ve been in your shoes. Started tracking my personal finances and rental properties solo about 4 years ago, then needed to collaborate with my CPA during tax season. The first time we tried working on the same ledger… let’s just say we learned some lessons the hard way!

My Git Workflow (That Actually Works)

Here’s what I landed on after some trial and error:

Main branch = source of truth

  • This is sacred ground. Always balanced, always clean.
  • Protected from direct pushes (use GitHub/GitLab branch protection)
  • Nobody commits directly to main, ever.

Feature branches for time periods

  • Branch naming: 2026-03-mike and 2026-03-accountant-sarah
  • We each work on our assigned date ranges or account types
  • This naturally prevents most conflicts since we’re not touching the same lines

Pull requests with automated checks

  • Before merging, the PR must pass bean-check validation
  • We review each other’s balance assertions
  • Quick sanity check: “Does this look right to you?”

The magic ingredient: CI/CD automation

  • GitHub Actions (or GitLab CI) runs bean-check on every PR
  • If balance assertions fail, the PR can’t merge
  • Catches errors before they hit the main ledger

The Most Important Lesson

Start simple. Seriously.

Your instinct to plan ahead is good, but don’t build a NASA-level workflow before you’ve felt the pain points. Here’s what I’d suggest:

  1. Week 1: Just try having you and your junior work on separate months. See what breaks.
  2. Week 2-3: Add a simple review process (even just Slack message + manual check)
  3. Month 2: Formalize with pull requests if you’re feeling the need
  4. Month 3: Add automation only if manual checking is becoming a bottleneck

The worst thing you can do is over-engineer before you understand the actual friction points. I spent 2 weeks setting up elaborate Git hooks and CI pipelines… then realized my accountant only touches my ledger 4 times a year. Total overkill.

Practical Tip: Pre-commit Hooks

If you want one automation to start with, it’s this:

# .git/hooks/pre-commit
#!/bin/bash
bean-check main.beancount
if [ $? -ne 0 ]; then
    echo "Balance check failed! Fix errors before committing."
    exit 1
fi

This prevents anyone (including yourself!) from committing broken ledgers. It’s saved me countless times.

Offer

I’ve got a simple Git hooks setup and a basic PR checklist template I’m happy to share. Nothing fancy, just practical stuff that works for a small team. DM me if you want them!

Good luck with the expansion, Bob. You’re thinking about this the right way - setting up good habits early pays dividends later.

Mike

3

Bob, this is a fantastic question and one that’s critically important for professional practices. Multi-user workflows aren’t just a technical convenience - they’re a compliance and quality control necessity for CPA firms.

Why This Matters for Professional Accounting

At Thompson & Associates, we manage books for 30+ small business clients. Every transaction that hits our clients’ ledgers needs to be:

  1. Accurate (obviously)
  2. Traceable (who entered it, when, and why)
  3. Reviewable (senior eyes on junior work before it’s “final”)
  4. Auditable (can we reconstruct what happened 3 years from now?)

Git + Beancount gives us all of this out of the box, which is why I’m such a huge advocate for plain text accounting in professional settings.

Our Workflow: Adapted GitHub Flow

We use a modified GitHub Flow approach:

Protected main branch

  • Main is always production-ready (balanced, reconciled, ready for client reports)
  • Requires pull request approval from a senior accountant
  • No one, not even me, can push directly to main

Client-specific feature branches

  • Naming convention: client-{clientname}-{period}
  • Examples: client-acmecorp-2026-q1, client-widgetco-2026-march
  • Each accountant works on their assigned client branches
  • Long-lived branches (quarterly) work better for us than monthly

Mandatory Code Review (Really “Ledger Review”)

  • Junior accountants create PR when month/quarter is complete
  • Senior accountant reviews before approval
  • PR checklist (we have a template):
    • All balance assertions pass
    • Bank reconciliation complete with supporting docs
    • Receipts linked for material expenses
    • Chart of accounts followed correctly
    • No uncommitted/stray transactions
    • Comments added for unusual entries

Why This Protects You From Errors

The review process is what saves you. Examples from our firm:

  • Caught duplicated invoice entry (would have overstated expenses by $12K)
  • Found misclassified expense (loan payment as expense instead of liability reduction)
  • Spotted missing balance assertion (would have hidden a $500 reconciliation gap)

Git blame becomes your accountability tool. If the IRS asks “who entered this deduction?”, you know exactly who, when, and what they were thinking (commit message).

Tool Recommendations

For your 2-person team:

  • GitHub (free private repos) or GitLab
  • Branch protection rules (easy to set up, huge safety net)
  • PR template with your review checklist
  • Simple CI/CD for automated bean-check (optional but nice)

For less technical teammates:

  • GitHub Desktop (GUI makes Git less scary)
  • Document your workflow in a simple README
  • Practice the PR process together before going live

What About Beancount.io v3 Collaboration?

The v3 collaboration features launched in late 2025 are excellent for client-facing collaboration (e.g., a bookkeeper working with a non-technical small business owner). The real-time features and web interface make it accessible.

For professional teams like yours and mine, I still prefer traditional Git workflows because:

  • More control over the review process
  • Better integration with our existing dev tools
  • Commit history is more detailed
  • Can use advanced Git features (bisect, revert, cherry-pick) when needed

That said, if your junior bookkeeper is not technical, Beancount.io’s collaboration UI might be the easier onramp. You can always migrate to pure Git later.

Final Thought

The review process is what protects you. Not the branching strategy, not the automation, not the tools. The review process.

Make it non-negotiable: No PR gets merged without a second set of eyes. This one rule will save you from more errors than any amount of automation ever could.

Good luck with the expansion, Bob. Feel free to reach out if you want to see our PR template or discuss more!

Alice Thompson, CPA
Thompson & Associates

4

This is such a cool problem, Bob! I don’t have multi-user needs personally (just me tracking toward FIRE), but I’ve been researching this exact topic because I’m fascinated by the automation possibilities.

The Automation Angle: Pre-commit Hooks + CI/CD

Mike and Alice both mentioned automated validation, and I want to double-click on this because it’s so powerful for catching errors before they become problems.

Pre-commit Hook (Local Validation)

Before any commit hits the repo, run validation:

#!/bin/bash
# .git/hooks/pre-commit

echo "Running Beancount validation..."
bean-check ledger/main.beancount

if [ $? -ne 0 ]; then
    echo "❌ Balance check failed! Fix errors before committing."
    exit 1
fi

echo "✅ Validation passed!"
exit 0

This is your first line of defense. Nobody (not even you) can commit broken ledgers.

GitHub Actions (CI/CD Validation)

On every pull request, automatically validate and report:

# .github/workflows/validate-ledger.yml
name: Validate Beancount Ledger

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Beancount
        run: pip install beancount
      
      - name: Validate ledger
        run: bean-check ledger/main.beancount
      
      - name: Generate balance report
        run: bean-report ledger/main.beancount balances > balance_summary.txt
      
      - name: Comment PR with results
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const balance = fs.readFileSync('balance_summary.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## Balance Summary\n\n\`\`\`\n${balance}\n\`\`\``
            });

This gives you automatic balance reports on every PR. Your reviewer can see at a glance if something looks off.

Branching Strategy Considerations

Your choice depends on how your team collaborates:

Per-client branches (if clients are independent ledgers)

  • client-acme, client-widgetco
  • Best when: Each client is a separate repo or file
  • Pros: Clean separation, no merge conflicts between clients
  • Cons: Doesn’t help if you’re both working on the same client

Per-time-period branches (if collaborating on same ledger)

  • 2026-03-bob, 2026-03-sarah
  • Best when: You naturally divide work by date ranges
  • Pros: Minimal conflicts (different dates = different file regions)
  • Cons: Can still conflict if you overlap date ranges

Trunk-based (if team is experienced and changes are small)

  • Everyone commits to main frequently (multiple times per day)
  • Best when: High trust, small changes, fast feedback loops
  • Pros: No merge debt, always up-to-date
  • Cons: Requires discipline and good communication

Quick question back to you, Bob: Are you managing multiple separate client ledgers (one repo per client)? Or one big multi-client ledger with all clients in a single file/repo?

This matters because if they’re separate, your collaboration complexity is much lower (no merge conflicts between different client work).

Fava Multi-File Support

One more thought: Fava supports multi-file ledgers with the include directive:

; main.beancount
include "clients/acme.beancount"
include "clients/widgetco.beancount"

This could let you and your junior work on completely separate client files with zero merge conflicts, then just include them all in a master file for reporting.

Looking Forward

The plain text accounting ecosystem is evolving fast. I wouldn’t be surprised if we see more collaboration-focused tooling in 2026-2027, especially around:

  • Real-time co-editing with conflict detection
  • Better mobile/offline sync
  • AI-assisted transaction categorization with review workflows

But for now, Git + automation is rock solid if you set it up thoughtfully.

Good luck, and please report back with what you decide! I’d love to hear how it works in practice.

Fred Chen
Seattle, WA