hledger Tags Tutorial Part 1: Or Don't Be Frightened This Halloween from Using This Useful Feature

[Robert Nielsen]

Don’t be scared away from using tags in your hledger accounting this Halloween, or any other time for that matter. This is the first part of a tutorial on using tags with hledger, so if the idea of using tags has been haunting you, but you are not really sure how to use them, read on.

 

Let’s start with a file showing someone’s Halloween hledger accounting:

 

; ================ Begin File ================

 

2016/09/25 ACME Costume

   Expenses:Entertainment     $45.99 ;Amoeba Man

   Liabilities:CreditCard

 

2016/10/31 Smiths

   Income:Treat   -1 candy

   Assets:Food

 

2016/10/31 Johnsons

   Income:Treat   -2 candy

   Assets:Food

 

2016/10/31 Ms. Miller

   Income:Treat   -1 candy

   Assets:Food

 

2016/10/31 Reids

   Income:Treat   -1 candy

   Assets:Food

 

2016/10/31 Mr. Freeman

   Income:Treat   -3 candy

   Assets:Food

 

2016/10/31 Potters

   Income:Treat   -1 candy

   Assets:Food

 

2016/11/01 Medical Associates

   Expenses:Medicial  $80.00 ;dyspepsia

   Liabilities:CreditCard

 

2016/12/15 West End Dentistry

   Expenses:Dental  $160.00 ;two fillings

   Liabilities:CreditCard

 

; ================ End File ================

 

We want to categorize all the above transactions as having to do with Halloween. One option would be to create a new category of expenses for Halloween, but what if we don’t want to lose the other categories, such as Entertainment, Medical, and Dental? One solution is to add a tag for Halloween.

 

Mechanics of Writing a Tag

 

One of the simplest tags is a word, which is inside a comment, immediately followed by a colon. In the file below, you will see all the transactions have had a tag, which I named Halloween, added to them:

 

; ================ begin file ================

 

2016/09/25 ACME Costume ; Halloween:

   Expenses:Entertainment     $45.99 ;Amoeba Man

   Liabilities:CreditCard

 

2016/10/31 Smiths ; Halloween:

   Income:Treat   -1 candy

   Assets:Food

 

2016/10/31 Johnsons ; Halloween:

   Income:Treat   -2 candy

   Assets:Food

 

2016/10/31 Ms. Miller ; Halloween:

   Income:Treat   -1 candy

   Assets:Food

 

2016/10/31 Reids ; Halloween:

   Income:Treat   -1 candy

   Assets:Food

 

2016/10/31 Mr. Freeman ; Halloween:

   Income:Treat   -3 candy

   Assets:Food

 

2016/10/31 Potters ; Halloween:

   Income:Treat   -1 candy

   Assets:Food

 

2016/11/01 Medical Associates ; Halloween:

   Expenses:Medicial  $80.00 ;dyspepsia

   Liabilities:CreditCard

 

2016/12/15 West End Dentistry ; Halloween:

   Expenses:Dental  $160.00 ;two fillings

   Liabilities:CreditCard

 

 

; ================ end file ================

Using Tags

 

Once we have tags, we can use them in a variety of ways. Here, we will look at one way, which is to use the tags to filter a command. For example, assume that the above file is named Halloween2.hledger.

 

This command:

 

hledger -f Halloween2.hledger register tag:Halloween

 

Produces something like the following output:

 

2016/09/25     ACME Costume           Liabilities:CreditCard   -$45.99          -$45.99

2016/11/01     Medical Associates     Liabilities:CreditCard   -$80.00         -$125.99

2016/12/15     West End Dentistry     Liabilities:CreditCard  -$160.00         -$285.99

 

Of course, if you have only the contents of the above file, you will get the same output whether or not you specify a tag in the command, but in real life you will have a multitude of transactions, only a few of which will be tagged Halloween. At that point, it becomes highly useful to narrow the scope of a command such as register, to apply to just those transactions with a specific tag.

 

And because we chose to use a tag, as opposed to creating a new expense category, we can still find out what we spent on dentistry, doctor’s bills, and so on. That is, if we total all the dentist expenses, it will include the Halloween dental costs as well as all the other dental costs.

 

But Wait, There’s More

 

My plan is to produce additional tutorials on tags, as this explanation has only scratched the surface. For example, tags can have values. Also, you can use pattern matching, or regular expressions, with tags. There is a command for listing your tags in a file. And there is even a pivot function. Stay tuned!

 

In Conclusion

 

Don’t think you have just a ghost of a chance of succeeding in using tags in hledger. They are a real treat to use, and you need to learn only a few tricks.

 

 

[Francesco Ariis]

On Mon, Oct 23, 2017 at 03:10:50PM -0700, Robert Nielsen wrote:
>

Excellent column Robert, keep them coming!
-F

[Simon Michael]

Thanks Robert - I love new docs, and you make them fun too! 

Let me know if you publish these on your site, so I can link. Or send pull requests adding them to the docs on hledger.org or plaintextaccounting.org. Or let me know if you'd like me to add them (and mention their license.)

This is a great topic. I'd like to see more discussion of the non-tag solution, spelling out in more detail why we wouldn't use, eg:

Expenses:Halloween

- no longer tracks entertainment vs medical vs ...

Halloween:Expenses:Entertainment

- no longer appears in incomestatement report, or grouped with other expenses in balance report

Expenses:Entertainment:Halloween

- Halloween keeps showing up in future expense reports unless you limit depth, which is extra work and affects all accounts

- account tree tends to get deeper and longer

or why we might still prefer to use them over tags:

- accounts are better supported by other tools, eg autocompletion in ledger-mode/hledger add/hledger-iadd

- accounts are more portable between ledgerlikes, so less data conversion work if you switch or temporarily run another

- why use two categorisation schemes when one will do

In the past I have been more pro-accounts and anti-tags than other people, and I tended to reach for style 3 above. Lately I've been favouring tags more, to keep accounts more consistent and simple over time. ; trip:YYYY:TRIPNAME is a new favourite of mine.

--
You received this message because you are subscribed to the Google Groups "hledger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hledger+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Simon Michael]

On Oct 23, 2017, at 4:10 PM, Simon Michael <si...@joyful.com> wrote:

Let me know if you publish these on your site, so I can link. Or send pull requests adding them to the docs on hledger.org or plaintextaccounting.org. Or let me know if you'd like me to add them (and mention their license.)

PS and ignore the above if you're just into writing right now. I suggest it for the future lest I forget.

[Robert Nielsen]

Thank you, and great discussion idea of comparing and contrasting tags vs. non-tag solutions!

I would be delighted to have these on the docs on one of the sites you mentioned. I will either send you a link or send a pull request.

[Simon Michael]

On Oct 23, 2017, at 3:10 PM, Robert Nielsen <niels...@gmail.com> wrote:

There is a command for listing your tags in a file.

This has an improved UI in master, by the way; it's now "hledger tags [TAGREGEX [QUERYARGS...]]