Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LEDGER(1)		FreeBSD	General	Commands Manual		     LEDGER(1)

NAME
     ledger -- Command-line, double-entry account reporting tool

SYNOPSIS
     ledger [options] [command]	[arguments]

DESCRIPTION
     ledger is a command-line accounting tool based on the power and complete-
     ness of double-entry accounting.  It is only a reporting tool, which
     means it never modifies your data files, but it does offer	a large	selec-
     tion of reports, and different ways to customize them to your needs.

COMMANDS
     ledger accepts several top-level commands,	each of	which generates	a dif-
     ferent kind of basic report.  Most	of them	accept a report-query argu-
     ment, in order to determine what should be	reported.  To understand the
     syntax of a report-query, see the section on QUERIES.  In its most	basic
     form, simply specifying one or more strings produces a report for all ac-
     counts containing those strings.

     If	no command is given, ledger enters a REPL, or command loop, allowing
     several commands to be executed on	the same dataset without reparsing.

     The following is a	complete list of accepted reporting commands:

     accounts [report-query]
	       List all	accounts for postings that match the report-query.

     balance [report-query]
	      Print a balance report showing totals for	postings that match
	      report-query, and	aggregate totals for parents of	those ac-
	      counts.  Options most commonly used with this command are:
	      --basis (-B)     Report in terms of cost basis, not amount or
			       value.  This is the only	form of	report which
			       is guaranteed to	always balance to zero,	when
			       no report-query is specified.  Only show	totals
			       for the top-most	accounts.
	      --empty (-E)     Show accounts whose total is zero.
	      --flat	       Rather than display a hierarchical tree,	flat-
			       ten the report to show subtotals	for only ac-
			       counts matching report-query.
	      --no-total       Suppress	the summary total shown	at the bottom
			       of the report.

	      The synonyms bal and b are also accepted.

     budget [report-query]
	      A	special	balance	report which includes three extra columns: the
	      amount budgeted during the reporting period, how spending	dif-
	      fered from the budget, and the percentage	of budget spent	(ex-
	      ceeds 100% if you	go over	budget).  Note that budgeting requires
	      one or more "periodic transactions" to be	defined	in your	data
	      file(s).	See the	manual for more	information.

     cleared [report-query]
	      A	special	balance	report which adds two extra columns: the
	      cleared balance for each account,	and the	date of	the most re-
	      cent cleared posting in that account.  For this accounting to be
	      meaningful, the cleared flag must	be set on at least one post-
	      ing.  See	the manual for more information.

     commodities [report-query]
	      List all commodities for postings	matching the report-query.

     convert  Reads data from a	CSV (comma-separated values) file and gener-
	      ates ledger transactions.

     csv [report-query]
	      Report of	postings matching the report-query in CSV format
	      (comma-separated values).	 Useful	for exporting data to a
	      spreadsheet for further analysis or charting.

     entry [entry-template]
	      Generate and display a new, properly formatted ledger transac-
	      tion by comparing	the entry-template to the transactions in your
	      data file(s).  For more information on draft templates and using
	      this command to quickly create new transactions, see the section
	      ENTRIES.

	      The synonym xact is also accepted.

     emacs [query]
	      Output posting and transaction data in a format readily consumed
	      by the Emacs editor, in a	series of Lisp forms.  This is used by
	      the Emacs	ledger-mode to process reporting data from ledger.

     equity [report-query]
	      Print a transaction with a series	of postings that balance cur-
	      rent totals for accounts matching	the report-query in a special
	      account called Equity:Opening Balances.  The purpose of this re-
	      port is to close the books for a prior year, while using these
	      equity postings to carry forward those balances.

     payees [report-query]
	      List all payees for postings matching the	report-query.

     pricemap
	      Produce a	file which can be used to generate a graph with
	      graphviz showing the relationship	of commodities in the ledger
	      file.

     prices [report-query]
	      Report prices for	all commodities	in postings matching the
	      report-query.  The prices	are reported with the granularity of a
	      single day.

     pricedb [report-query]
	      Report prices for	all commodities	in postings matching the
	      report-query.  Prices are	reported down to the second, using the
	      same format as the ~/.pricedb file.

     print [report-query]
	      Print out	the full transactions of any matching postings using
	      the same format as they would appear in a	data file.  This can
	      be used to extract subsets from a	ledger file to transfer	to
	      other files.

     push [options]
	      In the REPL, push	a set of command-line options, so that they
	      will apply to all	subsequent reports.

     pop      In the REPL, pop any option settings that	have been pushed.

     register [report-query]
	      List all postings	matching the report-query.  This is one	of the
	      most common commands, and	can be used to provide a variety of
	      useful reports.  Options most commonly used with this command
	      are:

	      --average	(-A)   Show the	running	average, rather	than a running
			       total.
	      --current	(-c)   Don't show postings beyond the present day.
	      --exchange commodity (-X)
			       Render all values in the	given commodity, if a
			       price conversion	rate can be determined.	 Rates
			       are always displayed relative to	the date of
			       the posting they	are calculated for.  This
			       means a register	report is a historical value
			       report.	For current values, it may be prefer-
			       able to use the balance report.
	      --gain (-G)      Show any	gains (or losses) in commodity values
			       over time.
	      --head number    Only show the top number	postings.
	      --historical (-H)
			       Value commodities at the	time of	their acquisi-
			       tion.
	      --invert	       Invert the value	of amounts shown.
	      --market (-V)    Show current market values for all amounts.
			       This is determined in a somewhat	magical	fash-
			       ion.  It	is probably more straightforward to
			       use --exchange option.
	      --period time-period (-p)
			       Show postings only for the given	time-period.
	      --related	(-r)   Show postings that are related to those that
			       would have been shown.  It has the effect of
			       displaying the "other side" of the postings.
	      --sort value-expression (-S)
			       Sort postings by	evaluating the given
			       value-expression.  Note that a comma-separated
			       list of expressions is allowed, in which	case
			       each sorting term is used in order to determine
			       the final ordering.  For	example, to search by
			       date and	then amount, one would use:
				     ledger reg	--sort 'date, amount'
			       The sort	order may be controlled	with the '-'
			       sign. For example, to sort in reverse chrono-
			       logical order:
				     ledger reg	--sort '-date'
	      --tail number    Only show the last number postings.
	      --uncleared (-U)
			       Only show uncleared (i.e., recent) postings.

	      There are	also several grouping options that can be useful:

	      --by-payee (-P)  Group postings by common	payee names.
	      --daily (-D)     Group postings by day.
	      --weekly (-W)    Group postings by week (starting	on Sundays).
	      --start-of-week day
			       Set the start of	each report grouped by week to
			       the given day.
	      --monthly	(-M)   Group postings by month.
	      --quarterly      Group postings by fiscal	quarter.
	      --yearly (-Y)    Group postings by year.
	      --days-of-week   Group postings by the day of the	week on	which
			       they took place.
	      --subtotal (-s)  Group all postings together.  This is very sim-
			       ilar to the totals shown	by the balance report.

	      The synonyms reg and r are also accepted.

     server   This command requires that Python	support	be active.  If so, it
	      starts up	an HTTP	server listening for requests on port 9000.
	      This provides an alternate interface to creating and viewing re-
	      ports.  Note that	this is	very much a work-in-progress, and will
	      not be fully functional until a later version.

     select [sql-query]
	      List all postings	matching the sql-query.	 This command allows
	      to generate SQL-like queries, e.g.:
		    ledger select date,amount from posts where
		    account=~/Income/

     source   Parse a journal file and checks it for errors.  ledger will re-
	      turn success if no errors	are found.

     stats [report-query]
	      Provide summary information about	all the	postings matching
	      report-query.  It	provides information such as:
		    +o	Time range of all matching postings
		    +o	Unique payees
		    +o	Unique accounts
		    +o	Postings total
		    +o	Uncleared postings
		    +o	Days since last	posting
		    +o	Posts in the last 7 days
		    +o	Posts in the last 30 days
		    +o	Posts this month

     xml [report-query]
	      Output data relating to the current report in XML	format.	 It
	      includes all accounts and	commodities involved in	the report,
	      plus the postings	and the	transactions they are contained	in.
	      See the manual for more information.

OPTIONS
     --abbrev-len INT
	      Set the minimum length an	account	can be abbreviated to if it
	      doesn't fit inside the account-width.  If	INT is zero, then the
	      account name will	be truncated on	the right.  If INT is greater
	      than account-width then the account will be truncated on the
	      left, with no shortening of the account names in order to	fit
	      into the desired width.

     --account EXPR
	      Prepend EXPR to all accounts reported.  That is, the option
	      --account	"'Personal'" would tack	Personal: and --account
	      "tag('VAT')" would tack the value	of the VAT tag to the begin-
	      ning of every account reported in	a balance or register report.

     --account-width INT
	      Set the width of the account column in the register report to
	      INT characters.

     --actual (-L)
	      Report only real transactions, with no automated or virtual
	      transactions used.

     --add-budget
	      Show only	un-budgeted postings.

     --amount EXPR (-t)
	      Apply the	given value expression to the posting amount.  Using
	      --amount EXPR you	can apply an arbitrary transformation to the
	      postings.

     --amount-data (-j)
	      On a register report print only the dates	and amount of post-
	      ings.  Useful for	graphing and spreadsheet applications.

     --amount-width INT
	      Set the width in characters of the amount	column in the register
	      report.

     --anon   Anonymize	registry output, mostly	for sending in bug reports.

     --ansi   Use color	if the terminal	supports it.  Alias for	--color

     --args-only
	      Ignore init files	and environment	variables for the ledger run.

     --auto-match
	      When generating a	ledger transaction from	a CSV file using the
	      convert command, automatically match an account from the Ledger
	      journal.

     --aux-date
	      Show auxiliary dates for all calculations.  Alias	for
	      --effective

     --average (-A)
	      Print average values over	the number of transactions instead of
	      running totals.

     --average-lot-prices
	      Report the average price at which	each commodity was purchased
	      in a balance report.

     --balance-format FMT
	      Specify the format to use	for the	balance	report.

     --base   Reduce convertible commodities down the bottom of	the conver-
	      sion, e.g.  display time in seconds.

     --basis (-B)
	      Report the cost basis on all posting.  Alias for --cost

     --begin DATE (-b)
	      Specify the start	DATE of	all calculations.  Transactions	before
	      that date	will be	ignored.

     --bold-if EXPR
	      Print the	entire line in bold if the given value expression is
	      true.

     --budget
	      Only display budgeted items.  In a register report this displays
	      transaction in the budget, in a balance report this displays ac-
	      counts in	the budget.

     --budget-format FMT
	      Specify the format to use	for the	budget report.

     --by-payee	(-P)
	      Group postings in	the register report by common payee names.

     --check-payees
	      Enable strict and	pedantic checking for payees as	well as	ac-
	      counts, commodities and tags.

     --cleared (-C)
	      Display only cleared postings.

     --cleared-format FMT
	      Specify the format to use	for the	cleared	report

     --collapse	(-n)
	      Print only the top level accounts.

     --collapse-if-zero
	      Collapse the account display only	if it has a zero balance.

     --color  Use color	if the terminal	supports it.  Alias for	--ansi

     --columns INT
	      Make the register	report INT characters wide.  By	default	ledger
	      will use all available columns in	your terminal.

     --cost   Report the cost basis on all posting.  Alias for --basis.

     --count  Direct ledger to report the number of items when appended	to the
	      commodities, accounts or payees commands.

     --csv-format FMT
	      Format csv report	according to FMT.

     --current (-c)
	      Shorthand	for --limit 'date _= today'.

     --daily (-D)
	      Shorthand	for --period daily.

     --date EXPR
	      Transform	the date of the	transaction using EXPR.

     --date-format DATEFMT (-y)
	      Print dates using	DATEFMT.  Refer	to strftime(3) for details on
	      the format string	syntax.

     --datetime-format DATETIMEFMT
	      Print datetimes using DATETIMEFMT.  Refer	to strftime(3) for de-
	      tails on the format string syntax.

     --date-width INT
	      Specify the width, in characters,	of the date column in the
	      register report.

     --day-break
	      Break up register	report of timelog entries that span multiple
	      days by day.

     --days-of-week
	      Group transactions by the	days of	the week.  Alias for --dow.

     --dc     Display register or balance in debit/credit format If you	use
	      --dc with	either the register or balance commands, you will now
	      get separate columns for debits and credits.

     --debug STR
	      If ledger	has been built with debug options this will provide
	      extra data during	the run.

     --decimal-comma
	      Direct ledger to parse journals using the	European standard
	      comma as decimal separator, vice a period.

     --depth INT
	      Limit the	depth of the account tree.  In a balance report, for
	      example, --depth 2 will print balances only for accounts with
	      two levels, i.e.	Expenses:Entertainment but not
	      Expenses:Entertainment:Dining.  This is a	display	predicate,
	      which means it only affects display, not the total calculations.

     --detail
	      Related to convert command. Synonym to --rich-data option.

     --deviation
	      Report each posting's deviation from the average.	 It is only
	      meaningful in the	register and prices reports.

     --display EXPR (-d)
	      Display lines that satisfy the expression	EXPR.

     --display-amount EXPR
	      Apply a transformation to	the displayed amount.  This occurs af-
	      ter calculations occur.

     --display-total EXPR
	      Apply a transformation to	the displayed total.  This occurs af-
	      ter calculations occur.

     --dow    Group transactions by the	days of	the week.  Alias for
	      --days-of-week.

     --download
	      Cause quotes to be automagically downloaded, as needed, by run-
	      ning a script named getquote and expecting that script to	return
	      a	value understood by ledger.  A sample implementation of	a
	      getquote script, implemented in Perl, is provided	in the distri-
	      bution.  Downloaded quote	price are then appended	to the price
	      database,	usually	specified using	the environment	variable
	      LEDGER_PRICE_DB.

     --effective
	      Show auxiliary dates for all calculations.  Alias	for
	      --aux-date.

     --empty (-E)
	      Include empty accounts in	report.

     --end DATE	(-e)
	      Constrain	the report so that transactions	on or after DATE are
	      not considered.

     --equity
	      Related to the equity command.  Gives current account balances
	      in the form of a register	report.

     --exact  Report beginning and ending of periods by	the date of the	first
	      and last posting occurring in that period.

     --exchange	COMMODITY [, COMMODITY,	...] (-X)
	      Display values in	terms of the given COMMODITY.  The latest
	      available	price is used.

     --file FILE (-f)
	      Read journal data	from FILE.

     --first INT
	      Print the	first INT entries.  Opposite of	--last INT.  Alias for
	      --head.

     --flat   Force the	full names of accounts to be used in the balance re-
	      port.  The balance report	will not use an	indented tree.

     --force-color
	      Output TTY color codes even if the TTY doesn't support them.
	      Useful for TTYs that don't advertise their capabilities cor-
	      rectly.

     --force-pager
	      Force ledger to paginate its output.

     --forecast-while EXPR
	      Continue forecasting while VEXPR is true.	 Alias for --forecast.

     --forecast-years INT
	      Forecast at most INT years into the future.

     --format FMT (-F)
	      Use the given format string FMT to print output.

     --gain (-G)
	      Report net gain or loss for commodities that have	a price	his-
	      tory.

     --generated
	      Include auto-generated postings (such as those from automated
	      transactions) in the report, in cases where you normally
	      wouldn't want them.

     --group-by	EXPR
	      Group transaction	together in the	register report.  EXPR can be
	      anything,	although most common would be payee or commodity.  The
	      tag() function is	also useful here.

     --group-title-format FMT
	      Set the format for the headers that separate reports section of
	      a	grouped	report.	 Only has effect with a	--group-by EXPR	regis-
	      ter report.

     --head INT
	      Print the	first INT entries.  Opposite of	--tail INT.  Alias for
	      --first

     --help   Print this man page.

     --immediate
	      Evaluate calculations immediately	rather than lazily.

     --import FILE
	      Import FILE as Python module.

     --init-file FILE (-i)
	      Read FILE	before any other ledger	file.  This file may not con-
	      tain any postings, but it	may contain option settings.  To spec-
	      ify options in the init file, use	the same syntax	as the com-
	      mand-line, but put each option on	its own	line.

     --inject STR
	      Use STR amounts in calculations.	In case	you know what amount a
	      transaction should be, but the actual transaction	has the	wrong
	      value you	can use	metadata STR to	specify	the expected amount.

     --input-date-format DATEFMT
	      Specify the input	date format for	journal	entries.

     --invert
	      Change the sign of all reported values.

     --last INT.
	      Report only the last INT entries.	 Opposite of --first INT.
	      Only useful on a register	report.	 Alias for --tail.

     --leeway INT (-Z)
	      Alias for	--price-expr.

     --limit EXPR (-l)
	      Limit postings in	calculations.

     --lot-dates
	      Report the date on which each commodity in a balance report was
	      purchased.

     --lot-notes
	      Report the tag attached to each commodity	in a balance report.

     --lot-prices
	      Report the price at which	each commodity in a balance report was
	      purchased.

     --lots   Report the date and price	at which each commodity	was purchased
	      in a balance report.

     --lots-actual
	      Preserve the uniqueness of commodities so	they aren't merged
	      during reporting without printing	the lot	annotations.

     --market (-V)
	      Use the latest market value for all commodities.

     --master-account STR
	      Prepend all account names	with STR

     --meta STR
	      In the register report, prepend the transaction with the value
	      of the given tag STR.

     --meta-width INT
	      Specify the width	of the Meta column used	for the	--meta TAG op-
	      tions.

     --monthly (-M)
	      Shorthand	for --period monthly.

     --no-aliases
	      Aliases are completely ignored.

     --no-color
	      Suppress any color TTY output.

     --no-pager
	      Disables the pager on TTY	output.

     --no-revalued
	      Stop ledger from showing <Revalued> postings.

     --no-rounding
	      Don't output "<Adjustment>" postings.  Note that this will cause
	      the running total	to often not add up!  Its main use is for
	      --amount-data (-j) and --total-data (-J) reports.

     --no-titles
	      Suppress the output of group titles.

     --no-total
	      Suppress printing	the final total	line in	a balance report.

     --now DATE
	      Use DATE as the current date.  This affects the output when us-
	      ing --period, --begin, --end, or --current to decide which dates
	      lie in the past or future.

     --only EXPR
	      This is a	postings predicate that	applies	after certain trans-
	      forms have been executed,	such as	periodic gathering.

     --options
	      Display the options in effect for	this ledger invocation,	along
	      with their values	and the	source of those	values.

     --output FILE (-o)
	      Redirect the output of ledger to FILE.

     --pager STR
	      Use STR as the pager program.

     --payee  Sets a value expression for formatting the payee.	 In the
	      register report this prevents the	second entry from having a
	      date and payee for each transaction.

     --payee-width INT
	      Set the number of	columns	dedicated to the payee in the register
	      report to	INT.

     --pedantic
	      Accounts,	tags or	commodities not	previously declared will cause
	      errors.

     --pending
	      Use only postings	that are marked	pending.

     --percent (-%)
	      Calculate	the percentage value of	each account in	a balance re-
	      ports.  Only works for account that have a single	commodity.

     --period PERIOD (-p)
	      Define a period expression that sets the time period during
	      which transactions are to	be accounted.  For a register report
	      only the transactions that satisfy the period expression with be
	      displayed.  For a	balance	report only those transactions will be
	      accounted	in the final balances.

     --period-sort
	      Sort the posting within transactions using the given value ex-
	      pression.

     --permissive
	      Quiet balance assertions.

     --pivot TAG
	      Produce a	balance	pivot report "around" the given	TAG.

     --plot-amount-format FMT
	      Define the output	format for an amount data plot.

     --plot-total-format FMT
	      Define the output	format for a total data	plot.

     --prepend-format FMT
	      Prepend FMT to every line	of the output.

     --prepend-width INT
	      Reserve INT spaces at the	beginning of each line of the output.

     --price (-I)
	      Use the price of the commodity purchase for performing calcula-
	      tions.

     --price-db	FILE

     --price-exp STR (-Z)
	      Set the expected freshness of price quotes, in INT minutes.
	      That is, if the last known quote for any commodity is older than
	      this value, and if --download is being used, then	the Internet
	      will be consulted	again for a newer price.  Otherwise, the old
	      price is still considered	to be fresh enough.  Alias for
	      --leeway.

     --prices-format FMT
	      Set the format for the prices report.

     --pricedb-format FMT
	      Set the format expected for the historical price file.

     --primary-date
	      Show primary dates for all calculations.	Alias for
	      --actual-dates

     --quantity	(-O)
	      Report commodity totals (this is the default).

     --quarterly
	      Shorthand	for --period quarterly.

     --raw    In the print report, show	transactions using the exact same syn-
	      tax as specified by the user in their data file.	Don't do any
	      massaging	or interpreting.  Can be useful	for minor cleanups,
	      like just	aligning amounts.

     --real (-R)
	      Account using only real transactions ignoring virtual and	auto-
	      matic transactions.

     --recursive-aliases
	      Causes ledger to try to expand aliases recursively, i.e. try to
	      expand the result	of an earlier expansion	again, until no	more
	      expansions apply.

     --register-format FMT
	      Define the output	format for the register	report.

     --related (-r)
	      In a register report show	the related account.  This is the
	      other side of the	transaction.

     --related-all
	      Show all postings	in a transaction, similar to --related but
	      show both	sides of each transaction.

     --revalued
	      Report discrepancy in values for manual reports by inserting
	      <Revalued> postings.  This is implied when using the --exchange
	      (-X) or --market (-V) option.

     --revalued-only
	      Show only	<Revalued> postings.

     --revalued-total
	      Display the sum of the revalued postings as the running total,
	      which serves to show unrealized capital in a gain/losses report.

     --rich-data
	      When generating a	ledger transaction from	a CSV file using the
	      convert command, add CSV,	Imported, and UUID meta-data.

     --seed INT
	      Set the random seed to INT for the generate command.  Used as
	      part of development testing.

     --script FILE
	      Execute a	ledger script.

     --sort EXPR (-S)
	      Sort the register	report based on	the value expression EXPR.

     --sort-xacts
	      Sort the posting within transactions using the given value ex-
	      pression.

     --start-of-week STR
	      Use STR as the particular	day of the week	to start when using
	      the --weekly option.  STR	can be day names, their	abbreviations
	      like "Mon", or the weekday number	starting at 0 for Sunday.

     --strict
	      Accounts,	tags or	commodities not	previously declared will cause
	      warnings.

     --subtotal	(-s)
	      Report register as a single subtotal.

     --tail INT
	      Report only the last INT entries.	 Only useful on	a register re-
	      port.  Alias for --last INT

     --time-colon
	      Display the value	for commodities	based on seconds as hours and
	      minutes.	Thus 8100s will	be displayed as	2:15h instead of
	      2.25h.

     --time-report
	      Add two columns to the balance report to show the	earliest
	      checkin and checkout times for timelog entries.

     --total EXPR (-T)
	      Define a value expression	used to	calculate the total in re-
	      ports.

     --total-data (-J)
	      Show only	dates and totals to format the output for plots.

     --total-width INT
	      Set the width of the total field in the register report.

     --trace INT
	      Enable tracing.  The INT specifies the level of trace desired.

     --truncate	STR
	      Indicates	how truncation should happen when the contents of col-
	      umns exceed their	width.	Valid arguments	for STR	are leading,
	      middle, and trailing.  The default is smarter than any of	these
	      three, as	it considers sub-names within the account name (that
	      style is called "abbreviate").

     --unbudgeted
	      Show only	un-budgeted postings.

     --uncleared (-U)
	      Use only uncleared transactions in calculations and reports.

     --unrealized
	      Show generated unrealized	gain and loss accounts in the balance
	      report.

     --unrealized-gains
	      Allow the	user to	specify	what account name should be used for
	      unrealized gains.	 Defaults to Equity:Unrealized Gains.  Often
	      set in one's ~/.ledgerrc file to change the default.

     --unrealized-losses
	      Allow the	user to	specify	what account name should be used for
	      unrealized losses.  Defaults to Equity:Unrealized	Losses.	 Often
	      set in one's ~/.ledgerrc file to change the default.

     --unround
	      Perform all calculations without rounding	and display results to
	      full precision.

     --values
	      Show the values used by each tag when used in combination	with
	      the tags command.

     --value-expr EXPR
	      Set a global value expression annotation.

     --verbose
	      Print detailed information on the	execution of ledger.

     --verify
	      Enable additional	assertions during run-time.  This causes a
	      significant slowdown.  When combined with	--debug	CODE ledger
	      will produce memory trace	information.

     --verify-memory
	      Verify that every	constructed object is properly destructed.
	      This is for debugging purposes only.

     --version
	      Print version information	and exit.

     --weekly (-W)
	      Shorthand	for --period weekly.

     --wide (-w)
	      Assume 132 columns instead of the	TTY width.

     --yearly (-Y)
	      Shorthand	for --period yearly.

PRE-COMMANDS
     Pre-commands are useful when you aren't sure how a	command	or option will
     work.  The	difference between a pre-command and a regular command is that
     pre-commands ignore the journal data file completely, nor is the user's
     init file read.

     args / query
	      Evaluate the given arguments and report how ledger interprets it
	      against the following model transaction:

		    2004/05/27 Book Store
			; This note applies to all postings. :SecondTag:
			Expenses:Books		       20 BOOK @ $10
			; Metadata: Some Value
			; Typed:: $100 + $200
			; :ExampleTag:
			; Here follows a note describing the posting.
			Liabilities:MasterCard	      $-200.00

     eval     Evaluate the given value expression against the model transac-
	      tion.

     format   Print details of how ledger uses the given formatting descrip-
	      tion and apply it	against	a model	transaction.

     parse / expr
	      Print details of how ledger uses the given value expression de-
	      scription	and apply it against a model transaction.

     generate
	      Randomly generates syntactically valid ledger data from a	seed.
	      Used by the GenerateTests	harness	for development	testing.

     period   Evaluate the given period	and report how ledger interprets it.

     template
	      Shows the	insertion template that	the xact command generates.
	      This is a	debugging command.

QUERIES
     The syntax	for reporting queries can get somewhat complex.	 It is a se-
     ries of query terms with an implicit OR operator between them.  The fol-
     lowing terms are accepted:

     regex	    A bare string is taken as a	regular	expression matching
		    the	full account name.  Thus, to report the	current	bal-
		    ance for all assets	and liabilities, you would use:

			  ledger bal asset liab

     payee regex (@regex)
		    Query on the payee,	rather than the	account.

     tag regex (%regex)
		    Query on tags.

     note regex	(=regex)
		    Query on anything found in an item's note.

     code regex	(#regex)
		    Query on the xact's	optional code (which can be any	string
		    the	user wishes).

     term and term  Query terms	are joined by an implicit OR operator.	You
		    can	change this to AND by using the	and keyword.  For ex-
		    ample, to show food	expenditures occurring at Shakee's
		    Pizza, you could say:

			  ledger reg food and @Shakee

     term or term   When you wish to be	more explicit, use the OR operator.

     show

     not term	    Reverse the	logical	meaning	of the following term.	This
		    can	be used	with parentheses to great effect:

			  ledger reg food and @Shakee and not dining

     ( term )	    If you wish	to mix OR and AND operators, it	is often help-
		    ful	to surround logical units with parentheses.  NOTE: Be-
		    cause of the way some shells interpret parentheses,	you
		    should always escape them:

			  ledger bal \(	assets or liab \) and not food

EXPRESSIONS
     abs(value)	      Return the absolute value	of the given value.

     account	      Return the posting's account.

     account_base     Return the base account, i.e. everything after the last
		      account delimiter	':'.

     actual	      Return true if the transaction is	real, i.e not an auto-
		      mated or virtual transaction, false otherwise.

     amount	      Return the amount	of the posting.

     amount_expr      Return the calculated amount of the posting according to
		      the --amount option.

     ansify_if(value, color, bool)
		      Render the given value as	a string, applying the proper
		      ANSI escape codes	to display it in the given color if
		      bool is true.  It	typically checks the value of the op-
		      tion --color, for	example:
			    ansify_if(amount, blue, options.color)

     beg_line	      Line number where	entry for posting begins.

     beg_pos	      Character	position where entry for posting begins.

     ceiling(value)   Return the next integer of value toward +infinity.

     cleared	      Return true if the posting was cleared, false otherwise.

     code	      Return the transaction code, the string between the
		      parenthesis after	the date.

     commodity(value)
		      Return the commodity of value or the posting amount when
		      value was	not specified.

     date	      Return the date of the posting.

     end_line	      Line number where	entry for posting ends.

     end_pos	      Character	position where entry for posting ends.

     floor(value)     Return the next integer of value toward -infinity.

     filename	      The name of the ledger data file from whence the posting
		      came.

     format(string)   Evaluate string as format	just like the --format option.

     format_date(date, format)
		      Return the date as a string using	format.	 Refer to
		      strftime(3) for format string details.

     format_datetime(datetime, format)
		      Return the datetime as a string using format.  Refer to
		      strftime(3) for format string details.

     get_at(seq, index)
		      Return value at index from seq.  Used internally to con-
		      struct different reports.

     has_meta(tag)    Return true if the posting has metadata named tag, false
		      otherwise.

     has_tag(tag)     Return true if the posting has metadata named tag, false
		      otherwise.

     is_seq(value)    Return true if value is a	sequence. Used internally.

     join(value)      Replace all newlines in value with \n.

     justify(value, first_width, latter_width, right_justify, colorize)
		      Right or left justify the	string representing value.
		      The width	of the field in	the first line is given	by
		      first_width.  For	subsequent lines the width is given by
		      latter_width.  If	latter_width is	-1, first_width	is
		      used for all lines.  If right_justify is true then the
		      field is right justified within the width	of the field.
		      If it is false, then the field is	left justified and
		      padded to	the full width of the field.  If colorize is
		      true, then ledger	will honor color settings.

     market(value, datetime)
		      Return the price of value	at datetime.  Note that
		      datetime must be surrounded by brackets in order to be
		      parsed correctly,	e.g.  [2012/03/23].

     meta(name)	      Return the value of metadata named name.

     note	      Return the note for the posting.

     now	      Return the current datetime.

     options	      A	variable that allows access to the values of the given
		      command-line options using the long option names,	e.g.
		      to see whether --daily (-D) was given use	option.daily.

     payee	      Return the payee of the posting.

     percent(value_a, value_b)
		      Return the percentage of value_a in relation to value_b
		      (used as 100%).

     pending	      Return true if the posting is marked as pending, false
		      otherwise.

     percent(value_a, value_b)
		      Return the percentage of value_a in relation to value_b.

     print(value)     Print value to stdout.  Used internally for debugging.

     quantity(value)  Return the quantity of value for values that have	a per-
		      unit cost.

     quoted(expression)
		      Surround expression with double-quotes.

     quoted_rfc4180(expression)
		      Surround expression with double-quotes, compatible with
		      rfc 4180.

     real	      Return true if the transaction is	real, i.e not an auto-
		      mated or virtual transaction, false otherwise.

     roundto(value, n)
		      Return value rounded to n	digits.	 Does not affect for-
		      matting.

     should_bold      Return true if expression	given to --bold-if evaluates
		      to true.	Internal use only!

     scrub(value)     Clean value using	various	transformations	such as	round,
		      stripping	value annotations, and more.

     strip(value)     Strip value annotation from value.

     tag(name)	      Return the value of tag named name.

     to_amount(value)
		      Convert value to an amount.  Internal use	only!

     to_balance(value)
		      Convert value to a balance.  Internal use	only!

     to_boolean(value)
		      Convert value to a boolean.  Internal use	only!

     to_date(value)   Convert value to a date.	Internal use only!

     to_datetime(value)
		      Convert value to a datetime.  Internal use only!

     to_int(value)    Return the integer value for value.

     to_mask(value)   Convert value to a mask.	Internal use only!

     to_sequence(value)
		      Convert value to a sequence.  Internal use only!

     to_string(value)
		      Convert value to a character string.

     today	      Return today's date.

     total	      Return the total of the posting.

     total_expr	      Return the calculated total of the posting according to
		      the --total option.

     trim(value)      Trim leading and trailing	whitespace from	value.

     truncated(string, total_len, account_len)
		      Truncate string to total_len ensuring that each account
		      is at least account_len long.

     virtual	      Return true if the transaction is	virtual, e.g auto-
		      mated, false otherwise.

DEBUG COMMANDS
     In	addition to the	regular	reporting commands, ledger also	accepts	sev-
     eral debug	commands:

     args [report-query]
	      Display complete analysis	of how ledger interpreted the given
	      report-query.  Useful if you want	to understand how report
	      queries are translated into value	expressions.

     eval [value-expression]
	      Evaluate the given value-expression and prints the result.  For
	      more on value expressions, see the section EXPRESSIONS.

     format [format-string]
	      Display an analysis of how format-string was parsed, and what it
	      would look like applied to a sample transaction.	For more on
	      format strings, see the section FORMATS.

     generate
	      Generate 50 randomly composed yet	valid ledger transactions.

     parse [value-expression]
	      Parse the	given value-expression and display an analysis of the
	      expression tree and its evaluated	value.	For more on value ex-
	      pressions, see the section EXPRESSIONS.

     python [file]
	      Invoke a Python interpreter to read the given file.  What	is
	      special about this is that the ledger module is builtin, not
	      read from	disk, so it doesn't require ledger to be installed
	      anywhere,	or the shared library variants to be built.

     reload   Reload all data files for	the current session immediately.  Can
	      only be used in the REPL.

     template [draft-template]
	      Display information about	how draft-template was parsed.	See
	      the section on DRAFTS.

ENVIRONMENT
     Every option to ledger may	be set using an	environment variable if	the
     option has	a long name.  For example setting the environment variable
     LEDGER_DATE_FORMAT="%d.%m.%Y' will	have the same effect as	specifying
     --date-format '%d.%m.%Y' on the command-line.  Options on the command-
     line always take precedence over environment variable settings, however.

FILES
     ~/.ledgerrc
	      Your personal ledger initializations.

SEE ALSO
     beancount(1), hledger(1)

     The full documentation for	ledger is maintained as	a Texinfo manual.  If
     the info program is installed on your system, the command
	   info	ledger3
     should give you access to the complete manual.

AUTHORS
     John Wiegley <johnw@newartisans.com>

FreeBSD	13.0			March 15, 2019			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | OPTIONS | PRE-COMMANDS | QUERIES | EXPRESSIONS | DEBUG COMMANDS | ENVIRONMENT | FILES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ledger&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help