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

FreeBSD Manual Pages

  
 
  

home | help
task(1)				 User Manuals			       task(1)

NAME
       task - A	command	line todo manager.

SYNOPSIS
       task <filter> <command> [ <mods>	| <args> ]
       task --version

DESCRIPTION
       Taskwarrior is a	command	line todo list manager.	It maintains a list of
       tasks that you want to do, allowing you to  add/remove,	and  otherwise
       manipulate  them.  Taskwarrior has a rich set of	subcommands that allow
       you to do various things	with it.

       At the core, Taskwarrior	is a list processing program. You add text and
       additional  related  parameters and redisplay the information in	a nice
       way.  It	turns into a todo list program when you	add due	dates and  re-
       currence.  It  turns  into  an organized	todo list program when you add
       priorities, tags	(one word descriptors),	project	groups,	etc.

FILTER
       The <filter> consists of	zero  or  more	search	criteria  that	select
       tasks.	For example, to	list all pending tasks belonging to the	'Home'
       project:

	 task project:Home list

       You can specify multiple	filter terms, each of which further  restricts
       the result:

	 task project:Home +weekend garden list

       This  example  applies three filters: the 'Home'	project, the 'weekend'
       tag, and	the description	or annotations must contain the	character  se-
       quence  'garden'.   In  this example, 'garden' is translated internally
       to:

	 description.contains:garden

       as a convenient shortcut.  The 'contains' here is  an  attribute	 modi-
       fier,  which  is	used to	exert more control over	the filter than	simply
       absence or presence.  See the section 'ATTRIBUTE	MODIFIERS' below for a
       complete	list of	modifiers.

       Note  that a filter may have zero terms,	which means that all tasks ap-
       ply to the command.  This can be	dangerous, and this  special  case  is
       confirmed, and cannot be	overridden.  For example, this command:

	 task modify +work
	 This command has no filter, and will modify all tasks.	 Are you sure?
       (yes/no)

       will add	the 'work' tag to all tasks, but only after confirmation.

       More filter examples:

	 task					   <command> <mods>
	 task 28				   <command> <mods>
	 task +weekend				   <command> <mods>
	 task +bills due.by:eom			   <command> <mods>
	 task project:Home due.before:today	   <command> <mods>
	 task ebeeab00-ccf8-464b-8b58-f7f2d606edfb <command> <mods>

       By default filter elements are combined with an implicit	 'and'	opera-
       tor,  but 'or' and 'xor'	may also be used, provided parentheses are in-
       cluded:

	 task '( /[Cc]at|[Dd]og/ or /[0-9]+/ )'	     <command> <mods>

       The parentheses isolate the logical term	from any default command  fil-
       ter  or implicit	report filter which would be combined with an implicit
       'and'.

       A filter	may target specific tasks using	ID or UUID numbers.  To	 spec-
       ify  multiple  tasks use	one of these forms (space-separated list of ID
       numbers,	UUID numbers or	ID ranges):

	 task 1	2 3				       delete
	 task 1-3				       info
	 task 1	2-5 19				       modify pri:H
	 task 4-7 ebeeab00-ccf8-464b-8b58-f7f2d606edfb info

       Note that it may	be necessary to	properly escape	special	characters  as
       well  as	 quotes	in order to avoid their	special	meanings in the	shell.
       See also	the section 'SPECIFYING	DESCRIPTIONS' for more information.

MODIFICATIONS
       The <mods> consist of zero or more changes to  apply  to	 the  selected
       tasks, such as:

	 task <filter> <command> project:Home
	 task <filter> <command> +weekend +garden due:tomorrow
	 task <filter> <command> Description/annotation	text
	 task <filter> <command> /from/to/     <- replace first	match
	 task <filter> <command> /from/to/g    <- replace all matches

SUBCOMMANDS
       Taskwarrior  supports different kinds of	commands.  There are read com-
       mands, write commands, miscellaneous commands and  script  helper  com-
       mands.	Read  commands do not allow modification of tasks.  Write com-
       mands can alter almost any aspect of a task.   Script  helper  commands
       are  provided to	help you write add-on scripts, for example, shell com-
       pletion (only minimal output is generated,  as  with  verbose=nothing).
       Those commands which are	explicitly affected by the context are denoted
       as such.

READ SUBCOMMANDS
       Reports are read	subcommands. There are several reports currently  pre-
       defined	in  Taskwarrior. The output and	sort behavior of these reports
       can be configured in the	configuration file.  See  also	the  man  page
       taskrc(5).  There are also other	read subcommands that are not reports.

       task --version
	      This  is	the  only  conventional	 command  line	argument  that
	      Taskwarrior supports, and	is intended for	add-on scripts to ver-
	      ify  the	version	number of an installed Taskwarrior without in-
	      voking the mechanisms that create	default	files.

       task <filter>
	      With no command specified, the default command is	run,  and  the
	      filter applied.

       task <filter> active
	      Shows  all  tasks	 matching  the filter that are started but not
	      completed.

       task <filter> all
	      Shows all	tasks matching the filter, including parents of	recur-
	      ring tasks.

       task <filter> blocked
	      Shows  all tasks matching	the filter, that are currently blocked
	      by other tasks.

       task <filter> blocking
	      Shows all	tasks matching the filter, that	block other tasks.

       task <filter> burndown.daily
	      Shows a graphical	burndown chart,	by day.	 Is  affected  by  the
	      context.

       task <filter> burndown.weekly
	      Shows a graphical	burndown chart,	by week.  Note that 'burndown'
	      is an alias to the 'burndown.weekly' report. Is affected by  the
	      context.

       task <filter> burndown.monthly
	      Shows  a	graphical burndown chart, by month. Is affected	by the
	      context.

       task calendar [due|<month> <year>|<year>] [y]
	      Shows a monthly calendar with due	tasks marked.  Shows one hori-
	      zontal  line  of	months.	 If the	'y' argument is	provided, will
	      show at least one	complete year.	If a year is provided, such as
	      '2015',  then  that  full	 year is shown.	 If both a month and a
	      year are specified ('6 2015') then the months displayed begin at
	      the  specified  month  and  year.	 If the	'due' argument is pro-
	      vided, will show the starting month of the earliest due task.

       task colors [<sample> | legend]
	      Displays all possible colors, a named sample, or a  legend  con-
	      taining all currently defined colors.

       task columns [<substring>]
	      Displays	all  supported	columns	and formatting styles.	Useful
	      when creating custom reports.  If	a substring is provided,  only
	      matching column names are	shown.

       task commands
	      Shows all	the supported commands,	with some details of each.

       task <filter> completed
	      Shows all	tasks matching the filter that are completed.

       task <filter> count
	      Displays	only a count of	tasks matching the filter. Is affected
	      by the context.

       task <filter> export
	      Exports all tasks	in the JSON format.  Redirect the output to  a
	      file,  if	 you wish to save it, or pipe it to another command or
	      script to	convert	it to another format. You'll find these	 exam-
	      ple scripts online at <https://taskwarrior.org/tools/>:

		export-csv.pl
		export-sql.py
		export-xml.py
		export-yaml.pl
		export-html.pl
		export-tsv.pl
		export-xml.rb
		export-ical.pl
		export-xml.pl
		export-yad.pl

       task <filter> ghistory.annual
	      Shows a graphical	report of task status by year.

       task <filter> ghistory.monthly
	      Shows  a	graphical  report  of task status by month.  Note that
	      'ghistory' is an alias to	'ghistory.monthly'.

       task <filter> ghistory.weekly
	      Shows a graphical	report of task status by week.

       task <filter> ghistory.daily
	      Shows a graphical	report of task status by day.

       task help
	      Shows the	long usage text.

       task <filter> history.annual
	      Shows a report of	task history by	year. Is affected by the  con-
	      text.

       task <filter> history.monthly
	      Shows a report of	task history by	month.	Note that 'history' is
	      an alias to 'history.monthly'. Is	affected by the	context.

       task <filter> history.weekly
	      Shows a report of	task history by	week. Is affected by the  con-
	      text.

       task <filter> history.daily
	      Shows  a	report of task history by day. Is affected by the con-
	      text.

       task <filter> ids
	      Applies the filter then extracts only the	task IDs and  presents
	      them  as	a  space-separated list.  This is useful as input to a
	      task command, to achieve this:

		task $(task project:Home ids) modify priority:H

	      This example first gets the IDs  for  the	 project:Home  filter,
	      then  sets  the priority to H for	each of	those tasks.  This can
	      also be achieved directly:

		task project:Home modify priority:H

	      This command is mainly of	use to external	scripts.

       task <filter> uuids
	      Applies the filter on all	 tasks	(even  deleted	and  completed
	      tasks)  then extracts only the task UUIDs	and presents them as a
	      space-separated list.  This is useful as input to	 a  task  com-
	      mand, to achieve this:

		task  $(task  project:Home status:completed uuids) modify sta-
	      tus:pending

	      This example first gets the UUIDs	for the	project:Home and  sta-
	      tus:completed  filters,  then  makes each	of those tasks pending
	      again.

	      This command is mainly of	use to external	scripts.

       task udas
	      Shows a list of UDAs that	are  defined,  including  their	 name,
	      type,  label  and	 allowed values.  Also shows UDA usage and any
	      orphan UDAs.

       task <filter> information
	      Shows all	data and metadata for the specified  tasks.   This  is
	      the  only	 means	of displaying all aspects of a given task, in-
	      cluding the change history.

       task <filter> list
	      Provides a standard listing of tasks matching the	filter.

       task <filter> long
	      Provides the most	detailed listing of tasks matching the filter.

       task <filter> ls
	      Provides a short listing of tasks	matching the filter.

       task <filter> minimal
	      Provides a minimal listing of tasks matching the filter.

       task <filter> newest
	      Shows the	newest tasks matching the filter.

       task <filter> next
	      Shows a page of the most urgent tasks, sorted by urgency,	 which
	      is a calculated value.

       task <filter> ready
	      Shows  a	page of	the most urgent	ready tasks, sorted by urgency
	      with started tasks first.	A ready	task is	one that is either un-
	      scheduled, or has	a scheduled date that is past and is not wait-
	      ing.

       task <filter> oldest
	      Shows the	oldest tasks matching the filter.

       task <filter> overdue
	      Shows all	incomplete tasks matching the filter that  are	beyond
	      their due	date.

       task <filter> projects
	      Lists  all  project  names  that	are  currently used by pending
	      tasks, and the number of tasks for each. Is affected by the con-
	      text.

       task <filter> recurring
	      Shows all	recurring tasks	matching the filter.

       task <filter> unblocked
	      Shows  all  tasks	that are not currently blocked by other	tasks,
	      matching the filter.

       task <filter> waiting
	      Shows all	waiting	tasks matching the filter.

WRITE SUBCOMMANDS
       task add	<mods>
	      Adds a new pending task to the task list.	It is affected by  the
	      currently	set context.

       task <filter> annotate <mods>
	      Adds an annotation to an existing	task.

       task <filter> append <mods>
	      Appends description text to an existing task.

       task <filter> delete <mods>
	      Deletes  the  specified  task from task list. Is affected	by the
	      context.

       task <filter> denotate <mods>
	      Deletes an annotation for	the specified task.  If	 the  provided
	      description matches an annotation	exactly, the corresponding an-
	      notation is deleted. If the provided description matches annota-
	      tions partly, the	first partly matched annotation	is deleted. Is
	      affected by the context.

       task <filter> done <mods>
	      Marks the	specified task as done.	Is affected by the context.

       task <filter> duplicate <mods>
	      Duplicates the specified task and	allows modifications.  Is  af-
	      fected by	the context.

       task <filter> edit
	      Launches	a  text	editor to let you modify all aspects of	a task
	      directly.	 In general, this is not  the  recommended  method  of
	      modifying	 tasks,	but is provided	for exceptional	circumstances.
	      Use carefully. Is	affected by the	context.

       task import [<file> ...]
	      Imports tasks in the JSON	format.	 Can be	used to	add new	tasks,
	      or update	existing ones.	Tasks are identified by	their UUID.

	      If no file or "-"	is specified, import tasks from	STDIN.

	      Setting  rc.recurrence.confirmation  to  an appropriate level is
	      recommended if import is to be used in automated workflows.  See
	      taskrc(5).

	      For  importing  other  file  formats,  the standard task release
	      comes with a few example scripts,	such as:

		import-todo.sh.pl
		import-yaml.pl

       task log	<mods>
	      Adds a new task that is already completed, to the	task list.  It
	      is affected by the currently set context.

       task <filter> modify <mods>
	      Modifies the existing task with provided information.

       task <filter> prepend <mods>
	      Prepends	description  text  to an existing task.	Is affected by
	      the context.

       task <filter> purge
	      Permanently removes the specified	tasks  from  the  data	files.
	      Only  tasks that are already deleted can be purged. This command
	      has a local-only effect and changes introduced  by  it  are  not
	      synced.  Is affected by the context.

	      Warning: causes permanent, non-revertible	loss of	data.

       task <filter> start <mods>
	      Marks  the  specified  tasks as started. Is affected by the con-
	      text.

       task <filter> stop <mods>
	      Removes the start	time from the specified	task. Is  affected  by
	      the context.

MISCELLANEOUS SUBCOMMANDS
       Miscellaneous  subcommands  either accept no command line arguments, or
       accept non-standard arguments.

       task calc <expression>
	      Evaluates	an algebraic expression.  Can  be  used	 to  test  how
	      Taskwarrior  parses  and	evaluates  the expression given	on the
	      command line.

	      Examples:

		  task calc 1 +	1
		  2

		  task calc now	+ 8d
		  2015-03-26T18:06:57

		  task calc eom
		  2015-03-31T23:59:59

       task config [<name> [<value> | '']]
	      Add, modify and remove settings directly in the Taskwarrior con-
	      figuration.   This  command  either  modifies the	'name' setting
	      with a new value of 'value', or adds a new entry that is equiva-
	      lent to 'name=value':

		  task config name value

	      This  command  sets  a blank value.  This	has the	effect of sup-
	      pressing any default value:

		  task config name ''

	      Finally, this command removes  any  'name=...'  entry  from  the
	      .taskrc file:

		  task config name

       task context <name>
	      Sets the currently active	context. See the CONTEXT section.

	      Example:

		  task context work

       task context delete <name>
	      Deletes  the  context with the name <name>. If the context being
	      deleted is currently set as active, it will be unset.

	      Example:

		  task context delete work

       task context define <name> <filter>
	      Defines a	new context with name <name> and definition  <filter>.
	      This  command  does  not	affect the currently set context, just
	      adds a new context definition.

	      Examples:

		  task context define work project:Work
		  task context define home project:Home	or +home
		  task context define superurgent due:today and	+urgent

       task context list
	      Outputs a	list of	available contexts along  with	their  defini-
	      tions.

       task context none
	      Clears the currently active context, if any was set.

       task context show
	      Shows the	currently active context, along	with its definition.

       task diagnostics
	      Shows  diagnostic	information, of	the kind needed	when reporting
	      a	problem.  When you report a bug, it is likely that  the	 plat-
	      form, version, and environment are important.  Running this com-
	      mand generates a summary of similar information that should  ac-
	      company a	bug report.

	      It includes compiler, library and	software information.  It does
	      not include any personal information, other  than	 the  location
	      and size of your task data files.

	      This  command also performs a diagnostic scan of your data files
	      looking for common problems, such	as duplicate UUIDs.

       task execute <external command>
	      Executes the specified command.  Not useful by itself, but  when
	      used  in	conjunction  with  aliases  and	extensions can provide
	      seamless integration.

       task logo
	      Displays the Taskwarrior logo.

       task news
	      Guides the user through important	release	notes  anytime	a  new
	      version  of  Taskwarrior	is installed. It provides personalized
	      feedback,	deprecation warnings and usage advice, where  applica-
	      ble.

       task reports
	      Lists  all  supported  reports.	This includes the built-in re-
	      ports, and any custom reports you	have defined.

       task show [all |	<substring>]
	      Shows all	the current settings.  If  a  substring	 is  specified
	      just the settings	containing that	substring will be displayed.

       task <filter> stats
	      Shows statistics of the tasks defined by the filter. Is affected
	      by the context.

       task <filter> summary
	      Shows a report of	aggregated task	status by project. Is affected
	      by the context.

       task sync [init]
	      The  sync	command	synchronizes data with the Taskserver, if con-
	      figured.

	      The init subcommand should only ever be run once,	 and  only  on
	      one  client,  because  it	sends all data to the Taskserver. This
	      allows all the subsequent	 sync  commands	 to  only  send	 small
	      deltas.

	      Note:  If	 you use multiple sync clients,	make sure this setting
	      (which is	the default) is	on your	primary	client:

		recurrence=on

	      and on all other clients (this is	not the	default):

		recurrence=off

	      This is a	workaround to avoid a recurrence bug  that  duplicates
	      recurring	tasks.

       task <filter> tags
	      Show  a  list  of	all tags used. Any special tags	used are high-
	      lighted. Note that virtual tags are not listed - they don't  re-
	      ally  exist,  and	 are just a convenient notation	for other task
	      metadata.	It is an error to attempt to add or remove  a  virtual
	      tag. Is affected by the context.

       task timesheet [<weeks>]
	      Shows a weekly report of tasks completed and started.

       task undo
	      Reverts the most recent action.  Obeys the confirmation setting.

       task version
	      Shows the	Taskwarrior version number.

HELPER SUBCOMMANDS
       task _aliases
	      Generates	a list of all aliases, for autocompletion purposes.

       task _columns
	      Displays only a list of supported	columns.

       task _commands
	      Generates	a list of all commands,	for autocompletion purposes.

       task _config
	      Lists all	supported configuration	variables, for completion pur-
	      poses.

       task _context
	      Lists all	available context variables, for completion purposes.

       task <filter> _ids
	      Shows only the IDs of matching tasks, in the  form  of  a	 list.
	      Deprecated in favor of _unique.

       task _show
	      Shows  the  combined defaults and	overrides of the configuration
	      settings,	for use	by third-party applications.

       task <filter> _unique <attribute>
	      Reports a	unique set of attribute	values.	For  example,  to  see
	      all the active projects:

		task +PENDING _unique project

       task <filter> _uuids
	      Shows  only  the	UUIDs  of matching tasks among all tasks (even
	      deleted and completed tasks), in the form	of a list.  Deprecated
	      in favor of _unique.

       task _udas
	      Shows only defined UDA names, in the form	of a list.

       task <filter> _projects
	      Shows  only a list of all	project	names used.  Deprecated	in fa-
	      vor of _unique.

       task <filter> _tags
	      Shows only a list	of all tags used, for autocompletion purposes.
	      Deprecated in favor of _unique.

       task <filter> _urgency
	      Displays the urgency measure of a	task.

       task _version
	      Shows only the Taskwarrior version number.

       task _zshcommands
	      Generates	 a  list  of all commands, for zsh autocompletion pur-
	      poses.

       task <filter> _zshids
	      Shows the	IDs and	descriptions of	matching tasks.

       task <filter> _zshuuids
	      Shows the	UUIDs and descriptions of matching tasks.

       task _get <DOM> [<DOM> ...]
	      Accesses and displays the	DOM reference(s).  Used	to extract in-
	      dividual values from tasks, or the system.  Supported DOM	refer-
	      ences are:

		rc.<name>
		tw.syncneeded
		tw.program
		tw.args
		tw.width
		tw.height
		tw.version
		context.program	   (Deprecated in 2.6.0)
		context.args	   (Deprecated in 2.6.0)
		context.width	   (Deprecated in 2.6.0)
		context.height	   (Deprecated in 2.6.0)
		system.version
		system.os
		<id>.<attribute>
		<uuid>.<attribute>

	      Note that	the 'rc.<name>'	reference may need to be escaped using
	      '--' to prevent the reference from being interpreted as an over-
	      ride.

	      Note that	if the DOM reference is	not valid,  or	the  reference
	      evaluates	to a missing value, the	command	exits with 1.

	      Additionally,  some  components  of the attributes of particular
	      types may	be extracted by	DOM references.

		$ task _get 2.due.year
		2015

	      For a full list of supported attribute-specific DOM  references,
	      consult	the   online   documentation   at:   <https://taskwar-
	      rior.org/docs/dom.html>

ATTRIBUTES AND METADATA
       ID     Tasks can	be specified uniquely by IDs, which are	simply the in-
	      dexes  of	 the  tasks  in	 the  data file.  The ID of a task may
	      therefore	change,	but only when a	command	is run	that  displays
	      IDs.   When modifying tasks, it is safe to rely on the last dis-
	      played ID.  Always run a report to check you have	the  right  ID
	      for a task. IDs can be given to task as a	sequence, for example,
	      task 1,4-10,19 delete

       +tag|-tag
	      Tags  are	arbitrary words	associated with	a task.	Use + to add a
	      tag and -	to remove a tag	from a task. A task can	have any quan-
	      tity of tags.

	      Certain  tags (called 'special tags'), can be used to affect the
	      way tasks	are treated.  For example, if a	task has  the  special
	      tag 'nocolor', then it is	exempt from all	color rules.  The sup-
	      ported special tags are:

		  +nocolor     Disable color rules processing for this task
		  +nonag       Completion of this task suppresses all nag mes-
	      sages
		  +nocal       This task will not appear on the	calendar
		  +next	       Elevates	task so	it appears on 'next' report

	      There  are  also	virtual	tags, which represent task metadata in
	      tag form.	 These tags do not exist, but can be  used  to	filter
	      tasks.  The supported virtual tags are:

		  ACTIVE       Matches if the task is started
		  ANNOTATED    Matches if the task has annotations
		  BLOCKED      Matches if the task is blocked
		  BLOCKING     Matches if the task is blocking
		  CHILD	       Matches if the task has a parent	(deprecated in
	      2.6.0)
		  COMPLETED    Matches if the task has completed status
		  DELETED      Matches if the task has deleted status
		  DUE	       Matches if the task is due
		  INSTANCE     Matches if the task is a	recurrent instance
		  LATEST       Matches if the task is the newest added task
		  MONTH	       Matches if the task is due this month
		  ORPHAN       Matches if the task has any orphaned UDA	values
		  OVERDUE      Matches if the task is overdue
		  PARENT       Matches if the task is a	parent (deprecated  in
	      2.6.0)
		  PENDING      Matches if the task has pending status
		  PRIORITY     Matches if the task has a priority
		  PROJECT      Matches if the task has a project
		  QUARTER      Matches if the task is due this quarter
		  READY	       Matches if the task is actionable
		  SCHEDULED    Matches if the task is scheduled
		  TAGGED       Matches if the task has tags
		  TEMPLATE     Matches if the task is a	recurrence template
		  TODAY	       Matches if the task is due today
		  TOMORROW     Matches if the task is due sometime tomorrow
		  UDA	       Matches if the task has any UDA values
		  UNBLOCKED    Matches if the task is not blocked
		  UNTIL	       Matches if the task expires
		  WAITING      Matches if the task is waiting
		  WEEK	       Matches if the task is due this week
		  YEAR	       Matches if the task is due this year
		  YESTERDAY    Matches if the task was due sometime yesterday

	      You  can	use  +BLOCKED to filter	blocked	tasks, or -BLOCKED for
	      unblocked	tasks.	Similarly,  -BLOCKED  is  equivalent  to  +UN-
	      BLOCKED.	It  is	an error to attempt to add or remove a virtual
	      tag.

       project:<project-name>
	      Specifies	the project to which a task is related to.

       priority:H|M|L or priority:
	      Specifies	High, Medium, Low and no priority for a	task.

       due:<due-date>
	      Specifies	the due-date of	a task.

       recur:<frequency>
	      Specifies	the frequency of a recurrence of a task.

       scheduled:<ready-date>
	      Specifies	the date after which a task can	be accomplished.

       until:<expiration date of task>
	      Specifies	the expiration date of a task, after which it will  be
	      deleted.

       limit:<number-of-rows>
	      Specifies	the desired number of tasks a report should show, if a
	      positive integer is given.  The value 'page' may also  be	 used,
	      and  will	 limit	the  report output to as many lines of text as
	      will fit on screen.  This	defaults to 25 lines.

       wait:<wait-date>
	      When a task is given a wait date,	it is hidden from most	built-
	      in  reports,  which  exclude  +WAITING.  When the	date is	in the
	      past, the	task is	not considered	+WAITING,  and	again  becomes
	      visible.	 Note  that, for compatibilty, such tasks are shown as
	      having status "waiting", but this	will change in	a  future  re-
	      lease.

       depends:<id1,id2	...>
	      Declares	this  task to be dependent on id1 and id2.  This means
	      that the tasks id1 and id2 should	be completed before this task.
	      Consequently,  this  task	will then show up on the 'blocked' re-
	      port.  It	accepts	a comma-separated list	of  ID	numbers,  UUID
	      numbers  and ID ranges.  When prefixing any element of this list
	      by '-', the specified tasks  are	removed	 from  the  dependency
	      list.

       entry:<entry-date>
	      For report purposes, specifies the date that a task was created.

ATTRIBUTE MODIFIERS
       Attribute modifiers improve filters.  Supported modifiers are:

	      before (synonyms under, below)
	      after (synonyms over, above)
	      by
	      none
	      any
	      is (synonym equals)
	      isnt (synonym not)
	      has (synonym contains)
	      hasnt
	      startswith (synonym left)
	      endswith (synonym	right)
	      word
	      noword

       They  can be applied to all regular attributes (see above) and the fol-
       lowing calculated attributes:

	      urgency (or short	urg)

       For example:

	      task due.before:eom priority.not:L list

       The before modifier is used to compare values, preserving semantics, so
       project.before:B	 list  all projects that begin with 'A'.  Priority 'L'
       is before 'M', and due:2011-01-01 is before due:2011-01-02.   The  syn-
       onyms  'under' and 'below' are included to allow	filters	that read more
       naturally.

       The after modifier is the inverse of the	before modifier.

       The by modifier is the same as 'before',	except it  also	 includes  the
       moment in question.  For	example:

	   task	add test due:eoy

       will be found when using	the inclusive filter 'by':

	   task	due.by:eoy

       but not when the	non-inclusive filter 'before' is used:

	   task	due.before:eoy

       this  applies  equally  to other	named dates such as 'eom', 'eod', etc;
       the modifier compares using '<='	rather than '<'	like 'before' does.

       The none	modifier requires that the attribute does not  have  a	value.
       For example:

	   task	priority:      list
	   task	priority.none: list

       are equivalent, and list	tasks that do not have a priority.

       The any modifier	requires that the attribute has	a value, but any value
       will suffice.

       The is modifier requires	an exact match with the	value.

       The isnt	modifier is the	inverse	of the is modifier.

       The has modifier	is used	to search for a	substring, such	as:

	   task	description.has:foo list
	   task	foo		    list

       These are equivalent and	will return any	task that has 'foo' in the de-
       scription or annotations.

       The hasnt modifier is the inverse of the	has modifier.

       The  startswith	modifier  matches against the left, or beginning of an
       attribute, such that:

	   task	project.startswith:H list
	   task	project:H	     list

       are equivalent and will match any project starting with 'H'.   Matching
       all projects not	starting with 'H' is done with:

	   task	project.not:H	      list

       The  endswith  modifier	matches	against	the right, or end of an	attri-
       bute.

       The word	modifier requires that the attribute contain  the  whole  word
       specified, such that this:

	   task	description.word:bar list

       Will match the description 'foo bar baz'	but does not match 'dog	food'.

       The noword modifier is the inverse of the word modifier.

EXPRESSIONS AND	OPERATORS
       You can use the following operators in filter expressions:

	 and  or  xor  !	       Logical operators
	 <  <=	=  ==  !=  !==	>=  >  Relational operators
	 (  )			       Precedence

       For example:

	 task due.before:eom priority.not:L list
	 task '( due < eom or priority != L )' list
	 task '! ( project:Home	or project:Garden )' list

       The  = operator tests for approximate equality.	Dates compare equal if
       they are	on the same day	(hour and minutes are ignored).	 Strings  com-
       pare  equal  if the left	operand	starts with the	right operand.	The ==
       operator	tests for exact	equality.  The != and !==  operators  are  the
       negation	of = and == respectively.  The negation	operator is !.

       Note  that  the	parentheses are	required when using a logical operator
       other than the 'and' operator.  The reason is that some reports contain
       filters that must be combined with the command line.  Consider this ex-
       ample:

	 task project:Home or project:Garden list

       While this looks	correct, it is not.  The 'list'	report contains	a fil-
       ter of:

	 task show report.list.filter

	 Config	Variable    Value
	 -----------------  --------------
	 report.list.filter status:pending

       Which means the example is really:

	 task status:pending project:Home or project:Garden list

       The implied 'and' operator makes	it:

	 task status:pending and project:Home or project:Garden	list

       This  is	a precedence error - the 'and' and 'or'	need to	be grouped us-
       ing parentheses,	like this:

	 task status:pending and ( project:Home	or project:Garden ) list

       The original example therefore must be entered as:

	 task '( project:Home or project:Garden	)' list

       This includes quotes to escape  the  parentheses,  so  that  the	 shell
       doesn't interpret them and hide them from Taskwarrior.

       There  is  redundancy  between operators, attribute modifiers and other
       syntactic sugar.	 For example, the following are	all equivalent:

	 task foo		       list
	 task /foo/		       list
	 task description.contains:foo list
	 task description.has:foo      list
	 task 'description ~ foo'      list

SPECIFYING DATES AND FREQUENCIES
   DATES
       Taskwarrior reads dates from the	command	line and displays dates	in the
       reports.	  The  expected	 and  desired date format is determined	by the
       configuration variable dateformat

	      Exact specification
		     task ... due:7/14/2008

	      ISO-8601
		     task ... due:2013-03-14T22:30:00Z

	      Relative wording
		     task ... due:now
		     task ... due:today
		     task ... due:yesterday
		     task ... due:tomorrow

	      Day number with ordinal
		     task ... due:23rd
		     task ... due:3wks
		     task ... due:1day
		     task ... due:9hrs

	      Start of next (work) week	(Monday),  calendar  week  (Sunday  or
	      Monday), month, quarter and year
		     task ... due:sow
		     task ... due:soww
		     task ... due:socw
		     task ... due:som
		     task ... due:soq
		     task ... due:soy

	      End  of current (work) week (Friday), calendar week (Saturday or
	      Sunday), month, quarter and year
		     task ... due:eow
		     task ... due:eoww
		     task ... due:eocw
		     task ... due:eom
		     task ... due:eoq
		     task ... due:eoy

	      At some point or later
		     task ... wait:later
		     task ... wait:someday

		     This sets the wait	date to	12/30/9999.

	      Next occurring weekday
		     task ... due:fri

	      Predictable holidays
		     task ... due:goodfriday
		     task ... due:easter
		     task ... due:eastermonday
		     task ... due:ascension
		     task ... due:pentecost
		     task ... due:midsommar
		     task ... due:midsommarafton
		     task ... due:juhannus

   FREQUENCIES
       Recurrence periods. Taskwarrior supports	several	ways of	specifying the
       frequency of recurring tasks.

	      daily, day, 1da, 2da, ...
		     Every day or a number of days.

	      weekdays
		     Mondays,  Tuesdays,  Wednesdays,  Thursdays,  Fridays and
		     skipping weekend days.

	      weekly, 1wk, 2wks, ...
		     Every week	or a number of weeks.

	      biweekly,	fortnight
		     Every two weeks.

	      monthly, month, 1mo, 2mo,	...
		     Every month.

	      quarterly, 1qtr, 2qtrs, ...
		     Every three months, a quarter, or a number	of quarters.

	      semiannual
		     Every six months.

	      annual, yearly, 1yr, 2yrs, ...
		     Every year	or a number of years.

	      biannual,	biyearly, 2yr
		     Every two years.

CONTEXT
       Context is a user-defined query,	which is automatically applied to  all
       commands	 that  filter  the  task  list and to commands that create new
       tasks (add, log). For example, any report command will have its	result
       affected	by the current active context.	Here is	a list of the commands
       that are	affected:

		  add
		  burndown
		  count
		  delete
		  denotate
		  done
		  duplicate
		  edit
		  history
		  log
		  prepend
		  projects
		  purge
		  start
		  stats
		  stop
		  summary
		  tags

	      All other	commands are NOT affected by the context.

		  $ task list
		  ID Age Project  Description	     Urg
		  1  2d	 Sport	  Run 5	miles	     1.42
		  2  1d	 Home	  Clean	the dishes   1.14

		  $ task context home
		  Context 'home' set. Use 'task	context	none' to remove.

		  $ task list
		  ID Age Project  Description	     Urg
		  2  1d	 Home	  Clean	the dishes   1.14
		  Context 'home' set. Use 'task	context	none' to remove.

	      Task list	got automatically filtered for project:Home.

		  $ task add Vaccuum the carpet
		  Created task 3.
		  Context 'home' set. Use 'task	context	none' to remove.

		  $ task list
		  ID Age Project  Description	      Urg
		  2  1d	 Home	  Clean	the dishes    1.14
		  3  5s	 Home	  Vaccuum the carpet  1.14
		  Context 'home' set. Use 'task	context	none' to remove.

	      Note  that  the  newly  added  task  "Vaccuum  the  carpet"  has
	      "project:Home" set automatically.

	      As  seen	in the example above, context is applied by specifying
	      its name to the "context"	command. To change the	currently  ap-
	      plied context, just pass the new context's name to the 'context'
	      command.

	      To unset any context, use	the 'none' subcommand.

		  $ task context none
		  Context unset.

		  $ task list
		  ID Age Project  Description	      Urg
		  1  2d	 Sport	  Run 5	miles	      1.42
		  2  1d	 Home	  Clean	the dishes    1.14
		  3  7s	 Home	  Vaccuum the carpet  1.14

	      Context can be defined using the 'define'	subcommand, specifying
	      both the name of the new context,	and it's assigned filter.

		  $ task context define	home project:Home
		  Are  you  sure  you  want  to	add 'context.home.read'	with a
	      value of 'project:Home'? (yes/no)	yes
		  Are you sure you want	to  add	 'context.home.write'  with  a
	      value of 'project:Home'? (yes/no)	yes
		  Context 'home' successfully defined.

	      Note  that  you  were  separately	prompted to set	the 'read' and
	      'write' context.	This allows you	to specify contexts that  only
	      work  for	 reporting  commands  or only for commands that	create
	      tasks.

	      To remove	the definition,	use the	'delete' subcommand.

		  $ task context delete	home
		  Are  you  sure  you  want  to	 remove	  'context.home.read'?
	      (yes/no) yes
		  Are  you  sure  you  want  to	 remove	 'context.home.write'?
	      (yes/no) yes
		  Context 'home' deleted.

	      To check what is the currently active context,  use  the	'show'
	      subcommand.

		  $ task context show
		  Context 'home' with

		  * read filter: '+home'
		  * write filter: '+home'

		  is currently applied.

	      Contexts can store arbitrarily complex filters.

		  $  task  context  define  family  project:Family or +paul or
	      +nancy
		  Are you sure you want	to add	'context.family.read'  with  a
	      value of 'project:Family or +paul	or +nancy'? (yes/no) yes
		  Are  you  sure you want to add 'context.family.write'	with a
	      value of 'project:Family or +paul	or +nancy'? (yes/no) no
		  Context 'family' successfully	defined.

	      Contexts are permanent, and the currently	set  context  name  is
	      stored in	the "context" configuration variable. The context def-
	      inition is stored	 in  the  "context.<name>.read"	 configuration
	      variable	(for  reporting	 commands)  and	"context.<name>.write"
	      configuration variable (for task additions, i.e. task add/log).

	      Note that	in the example above, the user decided not  to	define
	      the complex filter as writeable context. The reason for this de-
	      cision is	that the complex filter	in the example	does  not  di-
	      rectly  translate	 to a modification. In fact, if	such a context
	      is used as a writeable context, the following happens:

		  $ task add Call Paul
		  Created task 4.
		  Context 'family' set.	Use 'task context none'	to remove.

		  $ task 4 list
		  ID Age  Project Tags	     Description      Urg
		   4 9min Family  nancy	paul or	or Call	Paul	0

	      There is no clear	mapping	between	the complex  filter  used  and
	      the  modifications  (should  only	 the  project be set? only the
	      tags? both?). Additionally note the 'or' operators being present
	      in  the  description. Taskwarrior	does not try to	guess the user
	      intention	here, and instead, the user is	expected  to  set  the
	      "context.<name>.write"  variable	to  make  their	 intention ex-
	      plicit, for example:

		  $ task config	context.family.write project:Family
		  Are you sure you want	to change the value  of	 'context.fam-
	      ily.write'   from	  'project:Family   or	+paul  or  +nancy'  to
	      'project:Family'?	(yes/no) yes
		  Config file /home/tbabej/.config/task/taskrc modified.

		  $ task context
		  Name	 Type  Definition			 Active
		  family read  project:Family or +paul or +nancy yes
			 write project:Family			 yes
		  home	 read  +home				 no
			 write +home				 no

	      Note how read and	write contexts differ  for  context  "family",
	      while for	context	"home" they stay the same.

	      In addition, every configuration parameter can be	overridden for
	      the current context,  by	specifying  context.<name>.rc.<parame-
	      ter>. For	example, if the	default	command	for the	family context
	      should be	displaying the family_report:

		  $ task config	 context.family.rc.default.command  family_re-
	      port

COMMAND	ABBREVIATION
       All  Taskwarrior	commands may be	abbreviated as long as a unique	prefix
       is used,	for example:

	      $	task li

       is an unambiguous abbreviation for

	      $	task list

       but

	      $	task l

       could be	list, ls or long.

       Note that you can restrict the minimum abbreviation size	using the con-
       figuration setting:

	      abbreviation.minimum=3

SPECIFYING DESCRIPTIONS
       Some  task descriptions need to be escaped because of the shell and the
       special meaning of some characters to the shell.	This can be  done  ei-
       ther  by	adding quotes to the description or escaping the special char-
       acter:

	      $	task add "quoted ' quote"
	      $	task add escaped \' quote

       The argument -- (a double dash) tells Taskwarrior to  treat  all	 other
       args as description:

	      $	task add -- project:Home needs scheduling

       In  other  situations,  the  shell sees spaces and breaks up arguments.
       For example, this command:

	      $	task 123 modify	/from this/to that/

       is broken up into several arguments, which is corrected with quotes:

	      $	task 123 modify	"/from this/to that/"

       It is sometimes necessary to force the shell to pass quotes to Taskwar-
       rior intact, so you can use:

	      $	task add project:\'Three Word Project\'	description

       Taskwarrior supports Unicode using only the UTF8	encoding, with no Byte
       Order Marks in the data files.

CONFIGURATION FILE AND OVERRIDE	OPTIONS
       Taskwarrior stores its configuration in a file in the user's  home  di-
       rectory:	 ~/.taskrc.  The  default configuration	file can be overridden
       with:

       task rc:<path-to-alternate-file>	...
	      Specifies	an alternate configuration file	with highest priority.

       TASKRC=<path-to-alternate-file> task ..
	      The environment variable specifies  an  alternate	 configuration
	      file to use.

       XDG_CONFIG_HOME=<path-to-alternate-config-home> task ..
	      The  environment	variable  specifies an alternate configuration
	      file to use.

       task rc.<name>:<value> ...
	      task rc.<name>=<value> ...  Specifies  individual	 configuration
	      file overrides.

       TASKDATA=/tmp/.task task	...
	      The   environment	  variable  overrides  the  default,  and  the
	      'data.location' configuration setting of the  task  data	direc-
	      tory.

MORE EXAMPLES
       For examples please see the online documentation	starting at

	      <https://taskwarrior.org/docs>

       Note  that  the online documentation can	be more	detailed and more cur-
       rent than this man page.

FILES
       ~/.taskrc
	      User configuration file -	see also taskrc(5).   Note  that  this
	      can  be overridden on the	command	line or	by the TASKRC environ-
	      ment variable. Also, if ~/.taskrc	 doesn't  exist	 and  XDG_CON-
	      FIG_HOME environment variable is defined,	taskwarrior will check
	      if $XDG_CONFIG_HOME/task/taskrc exists and attempt to read it

       ~/.task
	      The default directory where task stores its data files. The  lo-
	      cation can be configured in the configuration variable 'data.lo-
	      cation', or overridden with the TASKDATA environment variable..

       ~/.task/pending.data
	      The file that contains the tasks that are	not yet	done.

       ~/.task/completed.data
	      The file that contains the completed ("done") tasks.

       ~/.task/undo.data
	      The file that contains information needed	by the "undo" command.

CREDITS	& COPYRIGHTS
       Copyright (C) 2006 - 2021 T. Babej, P. Beckingham, F. Hernandez.

       Taskwarrior is distributed under	the MIT	license. See https://www.open-
       source.org/licenses/mit-license.php for more information.

SEE ALSO
       taskrc(5), task-color(5), task-sync(5)

       For more	information regarding Taskwarrior, see the following:

       The official site at
	      <https://taskwarrior.org>

       The official code repository at
	      <https://github.com/GothenburgBitFactory/taskwarrior>

       You can contact the project by emailing
	      <support@GothenburgBitFactory.org>

REPORTING BUGS
       Bugs in Taskwarrior may be reported to the issue-tracker	at
	      <https://github.com/GothenburgBitFactory/taskwarrior/issues>

task 2.6.2			  2016-02-24			       task(1)

NAME | SYNOPSIS | DESCRIPTION | FILTER | MODIFICATIONS | SUBCOMMANDS | READ SUBCOMMANDS | WRITE SUBCOMMANDS | MISCELLANEOUS SUBCOMMANDS | HELPER SUBCOMMANDS | ATTRIBUTES AND METADATA | ATTRIBUTE MODIFIERS | EXPRESSIONS AND OPERATORS | SPECIFYING DATES AND FREQUENCIES | CONTEXT | COMMAND ABBREVIATION | SPECIFYING DESCRIPTIONS | CONFIGURATION FILE AND OVERRIDE OPTIONS | MORE EXAMPLES | FILES | CREDITS & COPYRIGHTS | SEE ALSO | REPORTING BUGS

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

home | help