doc:Tags: improve the Special tags list, and the tags doc generally
This commit is contained in:
Simon Michael
parent
baca5f8b54
commit
6103d74b4b
@ -1581,17 +1581,19 @@ except they may contain [tags](#tags), which are not ignored.
|
||||
|
||||
<!-- same section name as Commands > tags, if reordering these update all #tags[-1] links -->
|
||||
|
||||
Tags are a way to add extra labels or labelled data to transactions, postings, or accounts,
|
||||
Tags are a way to add extra labels or data fields to transactions, postings, or accounts,
|
||||
which you can then [search](#queries) or [pivot](#pivoting) on.
|
||||
|
||||
They are written as a word (optionally hyphenated) immediately followed by a full colon,
|
||||
in a transaction or posting or account directive's [comment](#account-comments).
|
||||
(This is an exception to the usual rule that things in comments are ignored.)
|
||||
You can write multiple tags separated by comma, and/or you can add more comment lines
|
||||
and write more tags there.
|
||||
A tag is a word, optionally hyphenated, immediately followed by a full colon,
|
||||
in the [comment](#account-comments) of a transaction, a posting, or an account directive.
|
||||
Eg: `2024-01-01 a transaction ; foo:`
|
||||
Note this is an exception to the usual rule that things in comments are ignored.
|
||||
|
||||
Here five different tags are recorded: one on the checking account,
|
||||
two on the transaction, and two on the expenses posting:
|
||||
You can write multiple tags on one line, separated by comma.
|
||||
Or you can write each tag on its own comment line (no comma needed in this case).
|
||||
|
||||
For example, here are five different tags:
|
||||
one on the `assets:checking` account, two on the transaction, and two on the `expenses:food` posting:
|
||||
|
||||
```journal
|
||||
account assets:checking ; accounttag:
|
||||
@ -1602,11 +1604,6 @@ account assets:checking ; accounttag:
|
||||
expenses:food $1 ; postingtag:, another-posting-tag:
|
||||
```
|
||||
|
||||
You can list tag names with `hledger tags [NAMEREGEX]`,
|
||||
or match by tag name with a `tag:NAMEREGEX` query.
|
||||
|
||||
### Tag inheritance
|
||||
|
||||
Postings also inherit tags from their transaction and their account.
|
||||
And transactions also acquire tags from their postings (and postings' accounts).
|
||||
So in the example above, the expenses posting effectively has all five tags
|
||||
@ -1615,46 +1612,60 @@ and the transaction also has all five tags (by acquiring from the expenses posti
|
||||
|
||||
### Tag names
|
||||
|
||||
Tag names are currently not very clearly specified; any sequence of non-whitespace characters
|
||||
followed by a colon may work.
|
||||
Most non-whitespace characters are allowed in tag names. Eg `😀:` is a valid tag.
|
||||
|
||||
The following tag names are generated by hledger or have special significance to hledger,
|
||||
so you may want to avoid using them yourself:
|
||||
You can list the tag names used in your journal with the [tags](#tags) command:\
|
||||
`hledger tags [NAMEREGEX]`
|
||||
|
||||
- `balances` -- a balance assertions transaction generated by close
|
||||
- `retain` -- a retain earnings transaction generated by close
|
||||
- `start` -- a opening balances, closing balances or balance assignment transaction generated by close
|
||||
- `generated-transaction` -- a transaction generated by --forecast
|
||||
- `generated-posting` -- a posting generated by --auto
|
||||
- `modified` -- a transaction which has had postings added by --auto
|
||||
- `type` -- declares an account's type in an account declaration
|
||||
- `t` -- stores the (user defined, single letter) type of a 15m unit of time parsed from timedot format
|
||||
In commands which use a [query](#queries), you can match by tag name. Eg:\
|
||||
`hledger print tag:NAMEREGEX`
|
||||
|
||||
Some additional tag names with an underscore prefix are used internally and not displayed
|
||||
in reports (but can be matched by queries):
|
||||
You can declare valid tag names with the [tag directive](#tag-directive) and then check them with the [check](#check) command.
|
||||
|
||||
- `_generated-transaction`
|
||||
- `_generated-posting`
|
||||
- `_modified`
|
||||
- `_conversion-matched`
|
||||
### Special tags
|
||||
|
||||
Some tag names have special significance to hledger,
|
||||
and could produce an error message if you use them wrongly (the `date:` tag in particular).
|
||||
They are explained elsewhere, but here is a list for reference:
|
||||
|
||||
<!-- keep synced with JournalChecks.hs -->
|
||||
```
|
||||
date -- overrides a posting's date
|
||||
date2 -- overrides a posting's secondary date
|
||||
type -- declares an account's type
|
||||
t -- appears on postings generated by timedot letters
|
||||
assert -- appears on txns generated by close --assert
|
||||
retain -- appears on txns generated by close --retain
|
||||
start -- appears on txns generated by close --migrate/--close/--open/--assign
|
||||
generated-transaction -- with --verbose-tags, appears on generated periodic txns
|
||||
generated-posting -- with --verbose-tags, appears on generated auto postings
|
||||
modified -- with --verbose-tags, appears on txns which have had auto postings added
|
||||
|
||||
Hidden tags used internally (and queryable):
|
||||
_generated-transaction -- always exists on generated periodic txns
|
||||
_generated-posting -- always exists on generated auto postings
|
||||
_modified -- always exists on txns which have had auto postings added
|
||||
_conversion-matched -- exists on postings which have been matched with a nearby @/@@ cost notation
|
||||
```
|
||||
|
||||
### Tag values
|
||||
|
||||
Tags can have a value, which is any text after the colon up until a comma or end of line
|
||||
(with surrounding whitespace removed).
|
||||
Note this means that hledger tag values can not contain commas.
|
||||
Tags can have a value, which is any text after the colon up until a comma or end of line, with surrounding whitespace removed.
|
||||
Ending at comma allows us to write multiple tags on one line, but also means that tag values can not contain commas.
|
||||
|
||||
Eg in the following posting, the three tags' values are "value 1", "value 2", and "" (empty) respectively:
|
||||
```journal
|
||||
expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz
|
||||
```
|
||||
|
||||
Note that tags can be repeated, and are additive rather than overriding:
|
||||
Multiple tags with the same name are additive rather than overriding:
|
||||
when the same tag name is seen again with a new value, the new name:value pair is added to the tags.
|
||||
(It is not possible to override a tag's value or remove a tag.)
|
||||
It is not possible to override a previous tag's value or remove a tag.
|
||||
|
||||
You can list a tag's values with `hledger tags TAGNAME --values`,
|
||||
or match by tag value with a `tag:NAMEREGEX=VALUEREGEX` query.
|
||||
You can list all the values used for a particular tag in the journal with\
|
||||
`hledger tags TAGNAME --values`
|
||||
|
||||
You can match on tag values with a query like `tag:NAMEREGEX=VALUEREGEX`
|
||||
|
||||
## Directives
|
||||
|
||||
@ -2299,7 +2310,7 @@ tag item-id
|
||||
Any indented subdirectives are currently ignored.
|
||||
|
||||
The ["tags" check](#check) will report an error if any undeclared tag name is used.
|
||||
It is quite easy to accidentally create a tag through normal use of colons in [comments](#comments];
|
||||
It is quite easy to accidentally create a tag through normal use of colons in [comments](#comments);
|
||||
if you want to prevent this, you can declare and check your tags .
|
||||
|
||||
## Periodic transactions
|
||||
|
||||
Loading…
Reference in New Issue
Block a user