Last updated on Dec 31, 2020
To get started, you need to install a few things:
JCF is built/run with
bazel. You should follow the instructions there to get it installed on your machine. I have not tested
bazel on Windows or Mac but assume it works.
Since JCF is a Java application you must also have a JDK installed. Instructions to do this are included in the
You need to install the
ledger-CLI to query and manage your general ledger. I’ve successfully compiled it from source on Ubuntu Linux but if you don’t care to go to that trouble, the website has precompiled binaries.
You’ll need git to clone JCF and my ledger scripts repository. Get it at https://git-scm.com/.
For convenience I like to structure all my repositories in a special directory. Usually
~/Development on my personal workstations.
Clone the tool Github repos
cd ~/Development git clone firstname.lastname@example.org:brentwalther/jcf.git git clone email@example.com:brentwalther/ledger-scripts.git
Create a personal repo for your ledger data
Since the ledger-CLI general ledger format is all text we can use
git to diff, update, and maintain snapshots of it.
In the below examples, I’m using a directory called
~/ledger-private-data as the repo:
- Copy the master accounts template:
cd ~/Development mkdir ledger-private-data cp ./jcf/examples/master.accounts ./ledger-private-data/master.accounts
ledger-private-data/master.accountsusing your favorite text editor. It is neither required nor recommended to set up all accounts now. Instead, inspect the expense and income account categories to determine whether they’re sufficient for your bookkeeping/budgeting purposes. After that, set up just one actual account to start (e.g. a
Liabilities:Credit Card:Bank 1234or
Assets:Current Assets:My Checking 1234account).
- Go ahead and create an empty
master.ledgerwhere we’ll merge other ledgers in to:
cd ~/Development touch ./ledger-private-data/master.ledger
- Create a
vars.shfor the ledger scripts:
cd ~/Development cp ./ledger-scripts/examples/vars.sh ./ledger-private-data/vars.sh
- Update the
vars.shfile. To start, you may fill in only the ledger executable, master ledger, and master accounts paths. You may leave out the commodities file if desired.
- Add an initial settings profiles files:
cd ~/Development cp ./jcf/examples/settings_profiles.textproto ./ledger-private-data/jcf_settings_profiles.textproto
- Initiliaze and create the initial commit in the repo:
cd ~/Development/ledger-private-data git init . git add -A git commit -m "Initial commit."
- (optional) Upload the repo to some private remote. I use Github.
Update the paths in
/ledger-scripts/vars.sh file to point to your personal
vars.sh you created in your private data repo using your favorite text editor. For example:
Then, edit your personal
vars.sh to contain the paths for all the data and tools on your own local environment. You should use
After you’ve cloned
ledger, and established a repository (as above), you’ve got everything you need to manage a general purpose version-controlled financial ledger.
Move on to importing a CSV.