{"id":17719900,"url":"https://github.com/jacoscaz/taskparser","last_synced_at":"2025-10-20T00:18:41.415Z","repository":{"id":259148401,"uuid":"873903351","full_name":"jacoscaz/taskparser","owner":"jacoscaz","description":"A CLI tool to extract tasks and worklogs out of Markdown documents.","archived":false,"fork":false,"pushed_at":"2025-02-28T10:07:29.000Z","size":84,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-06T14:57:35.699Z","etag":null,"topics":["extract","markdown","parser","tasks","todo"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jacoscaz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-16T23:21:28.000Z","updated_at":"2025-02-28T10:07:32.000Z","dependencies_parsed_at":"2024-10-25T10:28:05.555Z","dependency_job_id":"2b5784ad-2bc9-4999-997e-b394c688fe1b","html_url":"https://github.com/jacoscaz/taskparser","commit_stats":null,"previous_names":["jacoscaz/taskparser"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacoscaz%2Ftaskparser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacoscaz%2Ftaskparser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacoscaz%2Ftaskparser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacoscaz%2Ftaskparser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jacoscaz","download_url":"https://codeload.github.com/jacoscaz/taskparser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243520719,"owners_count":20304173,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["extract","markdown","parser","tasks","todo"],"created_at":"2024-10-25T15:12:53.898Z","updated_at":"2025-10-20T00:18:34.383Z","avatar_url":"https://github.com/jacoscaz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# taskparser\n\nA CLI tool to parse tasks and worklogs out of Markdown documents and print\nthem to standard output in the format of a Markdown table, CSV or JSON.\nSupports sorting and filtering based on metadata encoded in tags, inline and/or\nas YAML frontmatter.\n\n## Table of Contents\n\n- [taskparser](#taskparser)\n  - [Table of Contents](#table-of-contents)\n  - [Introduction](#introduction)\n  - [Example](#example)\n  - [Install](#install)\n  - [Usage](#usage)\n  - [Tags](#tags)\n    - [Choosing which tags to show](#choosing-which-tags-to-show)\n    - [Autogenerated tags](#autogenerated-tags)\n    - [Inline tags](#inline-tags)\n    - [Frontmatter tags](#frontmatter-tags)\n    - [Metadata file tags](#metadata-file-tags)\n    - [Heading tags](#heading-tags)\n    - [Tags in code blocks](#tags-in-code-blocks)\n    - [Filtering by tag](#filtering-by-tag)\n    - [Filtering by checked state](#filtering-by-checked-state)\n    - [Sorting by tag](#sorting-by-tag)\n  - [Worklogs](#worklogs)\n  - [License](#license)\n  - [Dependencies](#dependencies)\n\n## Introduction\n\nSee the [post on the rationale behind taskparser on my blog][intro].\n\n[intro]: https://treesandrobots.com/2024/10/taskparser-keep-notes-and-tasks-together.html\n\n## Example\n\nGiven directory `/foo/bar` with a `20241010-baz.md` file having the following\ncontents:\n\n```markdown\n## Todos\n\n- [ ] a pending task\n- [X] a completed task\n```\n\n`taskparser` will output the following:\n\n```\n$ taskparser /foo/bar\n```\n\n```\ntext             | done  | file            | date\n---              | ---   | ---             | ---\na pending task   | false | 20241010-baz.md | 20241010\na completed task | true  | 20241010-baz.md | 20241010\n```\n\n## Install\n\n```sh\nnpm i -g taskparser\n```\n\n## Usage\n\n```\n$ taskparser -h\nusage: taskparser [-h] [-t TAGS] [-f FILTER] [-s SORT] [-l] [-C] [-U] [-o {table,csv,json}] [-c COLUMNS] [-v] path\n\nA CLI tool to parse, sort and filter tasks and worklogs out of Markdown documents and print them to standard output, either in tabular of CSV format.\n\npositional arguments:\n  path                  working directory\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -t TAGS, --tags TAGS  comma-separated list of tags to show\n  -f FILTER, --filter FILTER\n                        filtering expression such as: foo(=bar)\n  -s SORT, --sort SORT  sorting expression such as: foo(asc)\n  -l, --worklogs        enable worklogs mode\n  -C, --checked         only show checked tasks\n  -U, --unchecked       only show unchecked tasks\n  -o {table,csv,json}, --out {table,csv,json}\n                        set output format\n  -c COLUMNS, --columns COLUMNS\n                        override detected terminal width (in character columns)\n  -v, --version         show program's version number and exit\n```\n\n## Tags\n\n`taskparser` uses the concept of _tag_ as the unit of information that\ndescribes tasks and worklogs.\n\n### Choosing which tags to show\n\nThe `-t` flag may be used to change which tags are displayed:\n\n```\n$ taskparser -t text,project,client,file,date /foo/bar\n```\n\n### Autogenerated tags\n\nWhen parsing tasks, `taskparser` auto-generates the following tags:\n\n| tag | description | internal | \n| --- | --- | --- |\n| `text` | the textual content of the task (first line only) | yes |\n| `file` | the file that contains the task | yes |\n| `date` | the date of creation of the task | no |\n| `checked` | whether the task is checked as done | yes |\n\nAuto-genereated tags considered _internal_ cannot be overridden via YAML\nfrontmatter or inline tags.\n\nWhen rendering to a Markdown table (i.e. the default output format `table`),\nthe `checked` tag is shortened to `c` and rendered with a tick mark for\ncompactness.\n\n### Inline tags\n\nTasks may be tagged inline:\n\n```markdown \n- [ ] a pending task #project(foo) #client(bar)\n- [X] a completed task\n```\n\n```\n$ taskparser -t text,project,client,file,date /foo/bar\n```\n\n```\ntext                                      | project | client | file            | date\n---                                       | ---     | ---    | ---             | ---\na pending task #project(foo) #client(bar) | foo     | bar    | 20241010-foo.md | 20241010\na completed task                          |         |        | 20241010-foo.md | 20241010\n```\n\nTags may also be added after a line break (three consecutive spaces) so that\nthey are not counted as part of the autogenerated `text` tag:\n\n```markdown \n- [ ] a pending task   \n      #project(foo) #client(bar)\n- [X] a completed task\n```\n\n```\n$ taskparser -t text,project,client,file,date /foo/bar\n```\n\n```\ntext             | project | client | file            | date\n---              | ---     | ---    | ---             | ---\na pending task   | foo     | bar    | 20241010-foo.md | 20241010\na completed task |         |        | 20241010-foo.md | 20241010\n```\n\n### Frontmatter tags\n\nIf present, tags will be inherited from any YAML front-matter:\n\n```markdown\n---\nproject: foo\nclient: bar\n---\n\n- [ ] a pending task\n- [X] a completed task\n```\n\n`taskparser` will produce:\n\n```\n$ taskparser -t text,project,client,file,date /foo/bar\n```\n\n```\ntext             | project | client | file            | date\n---              | ---     | ---    | ---             | ---\na pending task   | foo     | bar    | 20241010-foo.md | 20241010\na completed task | foo     | bar    | 20241010-foo.md | 20241010\n```\n\n### Metadata file tags\n\nIf present, tags will be inherited from any per-folder `.taskparser.yaml` files\nthroughout the folder hierarchy leading to a markdown file:\n\nTags **must** be expressed through a simple, root-level `tags` dictionary:\n\n```yaml\ntags:\n  project: foo\n  client: bar\n```\n\n### Heading tags\n\nIf present, tags will be inherited from headings. Each sub-heading may override\ntags from parent headings.\n\n```markdown\n# #client(foo)\n\n## #project(bar)\n\n- [ ] a pending task\n\n## #project(baz)\n\n- [X] a completed task\n```\n\n`taskparser` will produce:\n\n```\n$ taskparser -t text,project,client,file,date /foo/bar\n```\n\n```\ntext             | project | client | file            | date\n---              | ---     | ---    | ---             | ---\na pending task   | bar     | foo    | 20241010-foo.md | 20241010\na completed task | baz     | foo    | 20241010-foo.md | 20241010\n```\n\n### Tags in code blocks\n\nYAML fenced code blocks can also be used to set tags at the heading\nlevel when using the `taskparser` language identifier. Given:\n\n~~~markdown\n# primary\n\n```taskparser\nclient: foo\nproject: bar\n```\n\n- [ ] a pending task\n\n## secondary\n\n```taskparser\nproject: baz\n```\n\n- [X] a completed task\n~~~\n\n`taskparser` will produce:\n\n```\n$ taskparser -t text,client,project /foo/bar\n```\n\n```\ntext             | client | project\n----             | ------ | -------\na pending task   | foo    | bar    \na completed task | foo    | baz  \n```\n\n### Filtering by tag\n\n`taskparser` accepts filter expression via the `-f` argument:\n\n```shell\n$ taskparser -f \"client(=foo)\" /foo/bar\n```\n\nFiltering syntax is as follows:\n\n```\nfoo(isnull)      matches tasks without tag \"foo\"\nfoo(notnull)     matches tasks with tag \"foo\"\nfoo(=bar)        matches tasks with tag \"foo\" set to \"bar\"\nfoo(!=bar)       matches tasks with tag \"foo\" set to anything other than \"bar\"\nfoo(^=bar)       matches tasks with tag \"foo\" starting with \"bar\"\nfoo($=bar)       matches tasks with tag \"foo\" ending with \"bar\"\nfoo(*=bar*)      matches tasks with tag \"foo\" matching the pattern \"bar*\"\n```\n\nAdditionally, the following operators may be used to filter tasks based on the\nlexicographical ordering of tag values:\n\n```\nfoo(\u003e=bar)       matches tasks with tag \"foo\" greater than or equal to \"bar\"\nfoo(\u003c=bar)       matches tasks with tag \"foo\" lower than or equal to \"bar\"\nfoo(\u003ebar)        matches tasks with tag \"foo\" greater than \"bar\"\nfoo(\u003cbar)        matches tasks with tag \"foo\" lower than \"bar\"\n```\n\nFiltering expressions can be combined:\n\n```\nfoo(=bar),foo(!=baz)\n```\n\n### Filtering by checked state\n\nWhile filtering tasks by their checked state requires comparing against\n`\"true\"` and `\"false\"`, the `-U, --unchecked` and `-C, --checked` CLI\narguments make for easy-to-remember shortcuts:\n\n```\n$ taskparser -f \"checked(=false),project(=baz)\" /foo/bar\n$ taskparser -f \"checked(=true),project(=baz)\" /foo/bar\n```\n\nare equivalent to, respectively:\n\n```\n$ taskparser -U -f \"project(=baz)\" /foo/bar\n$ taskparser -C -f \"project(=baz)\" /foo/bar\n```\n\n### Sorting by tag\n\n`taskparser` accepts sorting expressions via the `-s` argument:\n\n```shell\n$ taskparser -s \"client(asc)\" /foo/bar\n```\n\nSorting syntax is as follows:\n\n```\nfoo(asc)      sorts tasks by the \"foo\" tag in ascending lexicographical order\nfoo(desc)     sorts tasks by the \"foo\" tag in descending lexicographical order\n```\n\nSorting expressions can be combined for nested sorting:\n\n```\nfoo(asc),bar(desc)\n```\n\n## Worklogs\n\nIn addition to tasks, `taskparser` can also collect and display _worklogs_.\nA worklog is a list item detailing a given amount of hours spent working.\n\n```markdown\n- WL:3h this is a simple worklog\n```\n\nWorklogs can be tagged, filtered and sorted exactly as tasks. For each worklog\nit encounters, `taskparser` automatically generates the following tags:\n\n| tag | description | internal | \n| --- | --- | --- |\n| `text` | the textual content of the task (first line only) | yes |\n| `file` | the file that contains the task | yes |\n| `date` | the date of creation of the task | no |\n| `hours` | amount of hours logged | yes |\n\nThe `-l` or `--worklogs` flag may be used to enable worklog mode:\n\n```\ntaskparser -l -t text,hours,file,date\n```\n\nWhen rendering to a Markdown table (i.e. the default output format), the\n`hours` tag is shortened to `h` for compactness.\n\n## License\n\nReleased under the LGPL v3.0 (`LGPL-3.0-only`) license. See [LICENSE.md][l1].\n\n## Dependencies\n\nThis package is published to NPM in bundle form, with no runtime dependencies.\n\nAll bundled dependencies are listed in the [DEPENDENCIES.md][l2] file, which\nincludes version numbers and licenses. This file is generated using the\n[`license-report` package][l3] as follows:\n\n```sh\nlicense-report --config license-report-config.json --output=markdown \u003e DEPENDENCIES.md\n```\n\n[l1]: ./LICENSE.md\n[l2]: ./DEPENDENCIES.md\n[l3]: https://www.npmjs.com/package/license-report\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacoscaz%2Ftaskparser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacoscaz%2Ftaskparser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacoscaz%2Ftaskparser/lists"}