{"id":18598158,"url":"https://github.com/bbugyi200/zorg","last_synced_at":"2025-07-20T08:33:14.532Z","repository":{"id":217400121,"uuid":"743774875","full_name":"bbugyi200/zorg","owner":"bbugyi200","description":"The zettel note manager of the future.","archived":false,"fork":false,"pushed_at":"2025-07-13T16:45:52.000Z","size":2828,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-13T18:35:15.708Z","etag":null,"topics":["cc-python","python"],"latest_commit_sha":null,"homepage":"https://zettel-org.readthedocs.io/en/latest","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbugyi200.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-16T00:46:54.000Z","updated_at":"2025-07-13T16:45:55.000Z","dependencies_parsed_at":"2024-04-05T23:31:31.797Z","dependency_job_id":"b5e0a762-20bf-4195-bae9-b235f92d9e9f","html_url":"https://github.com/bbugyi200/zorg","commit_stats":null,"previous_names":["bbugyi200/zorg"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/bbugyi200/zorg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbugyi200%2Fzorg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbugyi200%2Fzorg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbugyi200%2Fzorg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbugyi200%2Fzorg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbugyi200","download_url":"https://codeload.github.com/bbugyi200/zorg/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbugyi200%2Fzorg/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265190552,"owners_count":23725227,"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":["cc-python","python"],"created_at":"2024-11-07T01:31:14.438Z","updated_at":"2025-07-20T08:33:14.479Z","avatar_url":"https://github.com/bbugyi200.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zorg\n\n**The zettel note manager of the future.**\n\n_project status badges:_\n\n[![CI Workflow](https://github.com/bbugyi200/zorg/actions/workflows/ci.yml/badge.svg)](https://github.com/bbugyi200/zorg/actions/workflows/ci.yml)\n[![Coverage](https://codecov.io/gh/bbugyi200/zorg/branch/master/graph/badge.svg)](https://codecov.io/gh/bbugyi200/zorg)\n[![Documentation Status](https://readthedocs.org/projects/zettel-org/badge/?version=latest)](https://zettel-org.readthedocs.io/en/latest/?badge=latest)\n[![Package Health](https://snyk.io/advisor/python/zettel-org/badge.svg)](https://snyk.io/advisor/python/zettel-org)\n\n_version badges:_\n\n[![Project Version](https://img.shields.io/pypi/v/zettel-org)](https://pypi.org/project/zettel-org/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/zettel-org)](https://pypi.org/project/zettel-org/)\n[![Cookiecutter: cc-python](https://img.shields.io/static/v1?label=cc-python\u0026message=2024.01.16-4\u0026color=d4aa00\u0026logo=cookiecutter\u0026logoColor=d4aa00)](https://github.com/python-boltons/cc-python)\n[![Docker: pythonboltons/main](https://img.shields.io/static/v1?label=pythonboltons%20%2F%20main\u0026message=2024.10.09\u0026color=8ec4ad\u0026logo=docker\u0026logoColor=8ec4ad)](https://github.com/python-boltons/docker-python)\n\n\n## Installation 🗹\n\n### Using `pipx` to Install (preferred)\n\nThis package _could_ be installed using pip like any other Python package (in\nfact, see the section below this one for instructions on how to do just that).\nGiven that we only need this package's entry points, however, we recommend that\n[pipx][11] be used instead:\n\n```shell\n# install and setup pipx\npython3 -m pip install --user pipx\npython3 -m pipx ensurepath\n\n# install zorg\npipx install zettel-org\n```\n\n### Using `pip` to Install\n\nTo install `zorg` using [pip][9], run the following\ncommands in your terminal:\n\n``` shell\npython3 -m pip install --user zettel-org  # install zorg\n```\n\nIf you don't have pip installed, this [Python installation guide][10] can guide\nyou through the process.\n\n\n## Command-Line Interface (CLI)\n\nThe following subsections have been auto-generated using [cog][14]:\n\n### `zorg --help`\n\n\u003c!-- [[[[[kooky.cog\nimport subprocess\n\npopen = subprocess.Popen([\"zorg\", \"--help\"], stdout=subprocess.PIPE)\nstdout, _ = popen.communicate()\nprint(\"```\", stdout.decode().strip(), \"```\", sep=\"\\n\")\n\nfor cmd in [\n    \"action\",\n    \"action open\",\n    \"compile\",\n    \"db\",\n    \"db create\",\n    \"db reindex\",\n    \"edit\",\n    \"file\",\n    \"file rename\",\n    \"note\",\n    \"note move\",\n    \"note promote\",\n    \"query\",\n    \"template\",\n    \"template init\",\n    \"template list\",\n    \"template render\",\n]:\n    popen = subprocess.Popen([\"zorg\"] + cmd.split() + [\"--help\"], stdout=subprocess.PIPE)\n    stdout, _ = popen.communicate()\n    print(f\"\\n### `zorg {cmd} --help`\\n\")\n    print(\"```\", stdout.decode().strip(), \"```\", sep=\"\\n\")\n]]]]] --\u003e\n```\nusage: zorg [-h] [-c CONFIG_FILE] [-L [FILE[:LEVEL][@FORMAT]]] [-v]\n            [--version] [-d ZETTEL_DIR]\n            {action,compile,db,edit,file,note,query,template} ...\n\nThe zettel note manager of the future.\n\noptions:\n  -c CONFIG_FILE, --config CONFIG_FILE\n                        Absolute or relative path to a YAML file that contains\n                        this application's configuration.\n  -d ZETTEL_DIR, --dir ZETTEL_DIR\n                        The directory where all of your notes are stored.\n  -h, --help            show this help message and exit\n  -L [FILE[:LEVEL][@FORMAT]], --log [FILE[:LEVEL][@FORMAT]]\n                        This option can be used to enable a new logging\n                        handler. FILE should be either a path to a logfile or\n                        one of the following special file types: [1] 'stderr'\n                        to log to standard error (enabled by default), [2]\n                        'stdout' to log to standard out, [3] 'null' to disable\n                        all console (e.g. stderr) handlers, or [4] '+[NAME]'\n                        to choose a default logfile path (where NAME is an\n                        optional basename for the logfile). LEVEL can be any\n                        valid log level (i.e. one of ['CRITICAL', 'DEBUG',\n                        'ERROR', 'INFO', 'TRACE', 'WARNING']) and FORMAT can\n                        be any valid log format (i.e. one of ['color', 'json',\n                        'nocolor']). NOTE: This option can be specified\n                        multiple times and has a default argument of '+'.\n  -v, --verbose         How verbose should the output be? This option can be\n                        specified multiple times (e.g. -v, -vv, -vvv, ...).\n  --version             show program's version number and exit\n\nsubcommands:\n  {action,compile,db,edit,file,note,query,template}\n    action              Used to interface with vim via an action protocol.\n    compile             Compiles zorg (*.zo) files into zorc (*.zoc) files.\n    db                  Commands for managing Zorg's SQL database.\n    edit                Generate new day logs from templates and open the main\n                        day log in your system's editor. This is the default\n                        subcommand.\n    file                Commands for managing files.\n    note                Commands for managing individual notes.\n    query               Run a zorg query against your zettel directory.\n    template            Commands for managing .zot templates.\n```\n\n### `zorg action --help`\n\n```\nusage: zorg action [-h] {open} ...\n\nUsed to interface with vim via an action protocol.\n\noptions:\n  -h, --help  show this help message and exit\n\nsubcommands:\n  {open}\n    open      Open a zettel link if one exists on the provided zorg file line.\n```\n\n### `zorg action open --help`\n\n```\nusage: zorg action open [-h] zo_path line_number [option_idx]\n\nOpen a zettel link if one exists on the provided zorg file line.\n\npositional arguments:\n  line_number  The line number that your editor cursor is currently located\n               on.\n  option_idx   Used on a second 'action open' run to indicate which option was\n               selected.\n  zo_path      The file that your editor currently has open.\n\noptions:\n  -h, --help   show this help message and exit\n```\n\n### `zorg compile --help`\n\n```\nusage: zorg compile [-h] zo_path\n\nCompiles zorg (*.zo) files into zorc (*.zoc) files.\n\npositional arguments:\n  zo_path     Path to the zorg file you want to compile.\n\noptions:\n  -h, --help  show this help message and exit\n```\n\n### `zorg db --help`\n\n```\nusage: zorg db [-h] {create,reindex} ...\n\nCommands for managing Zorg's SQL database.\n\noptions:\n  -h, --help        show this help message and exit\n\nsubcommands:\n  {create,reindex}\n    create          Create zorg's backend database from scratch.\n    reindex         Reindex any changed files by adding them to the database.\n```\n\n### `zorg db create --help`\n\n```\nusage: zorg db create [-h] [-f]\n\nCreate zorg's backend database from scratch.\n\noptions:\n  -h, --help            show this help message and exit\n  -f, --update-error-file-whitelist\n                        If this option is NOT provided, any errors in Zorg\n                        files that are NOT already in the error file whitelist\n                        will cause Zorg to abort database creation.\n```\n\n### `zorg db reindex --help`\n\n```\nusage: zorg db reindex [-h] [paths ...]\n\nReindex any changed files by adding them to the database.\n\npositional arguments:\n  paths       Reindex these specific paths. If this argument is not provided,\n              we use a hashing approach to check which files have changed.\n\noptions:\n  -h, --help  show this help message and exit\n```\n\n### `zorg edit --help`\n\n```\nusage: zorg edit [-h] [zo_paths ...]\n\nGenerate new day logs from templates and open the main day log in your system's editor. This is the default subcommand.\n\npositional arguments:\n  zo_paths    The .zo files we want to open in an editor.\n\noptions:\n  -h, --help  show this help message and exit\n```\n\n### `zorg file --help`\n\n```\nusage: zorg file [-h] {rename} ...\n\nCommands for managing files.\n\noptions:\n  -h, --help  show this help message and exit\n\nsubcommands:\n  {rename}\n    rename    Rename a file.\n```\n\n### `zorg file rename --help`\n\n```\nusage: zorg file rename [-h] src_name dest_name\n\nRename a file.\n\npositional arguments:\n  dest_name   The destination filename.\n  src_name    The source filename.\n\noptions:\n  -h, --help  show this help message and exit\n```\n\n### `zorg note --help`\n\n```\nusage: zorg note [-h] {move,promote} ...\n\nCommands for managing individual notes.\n\noptions:\n  -h, --help      show this help message and exit\n\nsubcommands:\n  {move,promote}\n    move          Move a note to a different page.\n    promote       Promote a note to a file.\n```\n\n### `zorg note move --help`\n\n```\nusage: zorg note move [-h] zid new_page [note_type]\n\nMove a note to a different page.\n\npositional arguments:\n  new_page    Path to the destination page (i.e. where our note will be moved\n              to).\n  note_type   If provided, this argument specifies a new note type for the\n              moved note. This can be used, for example, to mark an OPEN todo\n              as DONE before moving it to a file dedicated to done todos.\n              Valid values: ['x', '~']\n  zid         ZID of the note we want to move.\n\noptions:\n  -h, --help  show this help message and exit\n```\n\n### `zorg note promote --help`\n\n```\nusage: zorg note promote [-h] [-n NEW_PAGE_NAME] [-p PARENT_PAGE_NAME] zid\n\nPromote a note to a file.\n\npositional arguments:\n  zid                   ZID of the note we want to promote to a file.\n\noptions:\n  -h, --help            show this help message and exit\n  -n NEW_PAGE_NAME, --new-page-name NEW_PAGE_NAME\n                        Name of the new page we create from the target note.\n                        Defaults to using the first ID property defined by the\n                        target note OR crashes if no ID property is found.\n  -p PARENT_PAGE_NAME, --parent-page-name PARENT_PAGE_NAME\n                        Name of the page that should be considered the parent\n                        of the new page we create. Defaults to the file\n                        containing the target note.\n```\n\n### `zorg query --help`\n\n```\nusage: zorg query [-h] [-e] [-s] query\n\nRun a zorg query against your zettel directory.\n\npositional arguments:\n  query                 The zorg query we will run.\n\noptions:\n  -h, --help            show this help message and exit\n  -e, --open-in-editor  Store query results in a temporary Zorg query page and\n                        then open this page in an editor.\n  -s, --store-in-file   Store query results in temporary Zorg query page and\n                        then print that page's file path to STDOUT.\n```\n\n### `zorg template --help`\n\n```\nusage: zorg template [-h] {init,list,render} ...\n\nCommands for managing .zot templates.\n\noptions:\n  -h, --help          show this help message and exit\n\nsubcommands:\n  {init,list,render}\n    init              Initialize a new file using a zorg template.\n    list              List all zorg template files.\n    render            Render a new .zo file using a .zot template.\n```\n\n### `zorg template init --help`\n\n```\nusage: zorg template init [-h] [-f] [-t TEMPLATE] new_path [variables ...]\n\nInitialize a new file using a zorg template.\n\npositional arguments:\n  new_path              Path to the new file you would like to create.\n  variables             A list of variable specs of the form of key=value.\n\noptions:\n  -f, --force           Overwrite target file if the file already exists.\n  -h, --help            show this help message and exit\n  -t TEMPLATE, --template TEMPLATE\n                        Optional path to the .zot template. If a template is\n                        not provided, we will infer what template to use based\n                        off of the new file's name.\n```\n\n### `zorg template list --help`\n\n```\nusage: zorg template list [-h]\n\nList all zorg template files.\n\noptions:\n  -h, --help  show this help message and exit\n```\n\n### `zorg template render --help`\n\n```\nusage: zorg template render [-h] template [variables ...]\n\nRender a new .zo file using a .zot template.\n\npositional arguments:\n  template    Path to the .zot template.\n  variables   A list of variable specs of the form of key=value.\n\noptions:\n  -h, --help  show this help message and exit\n```\n\u003c!-- [[[[[end]]]]] --\u003e\n\n\u003c!-- [[[[[kooky.cog\nfrom pathlib import Path\n\nlines = Path(\"./docs/design/design.md\").read_text().split(\"\\n\")\nif any(L.strip() for L in lines):\n    fixed_lines = [L.replace(\"(.\", \"(./docs/design\") if L.startswith(\"![\") else L for L in lines]\n    print(\"## Design Diagrams\\n\")\n    print(\"\\n\".join(fixed_lines))\n]]]]] --\u003e\n\u003c!-- [[[[[end]]]]] --\u003e\n\n\n## Useful Links 🔗\n\n* [API Reference][3]: A developer's reference of the API exposed by this\n  project.\n* [cc-python][4]: The [cookiecutter][5] that was used to generate this project.\n  Changes made to this cookiecutter are periodically synced with this project\n  using [cruft][12].\n* [CHANGELOG.md][2]: We use this file to document all notable changes made to\n  this project.\n* [CONTRIBUTING.md][7]: This document contains guidelines for developers\n  interested in contributing to this project.\n* [Create a New Issue][13]: Create a new GitHub issue for this project.\n* [Documentation][1]: This project's full documentation.\n\n\n[1]: https://zettel-org.readthedocs.io/en/latest\n[2]: https://github.com/bbugyi200/zorg/blob/master/CHANGELOG.md\n[3]: https://zettel-org.readthedocs.io/en/latest/modules.html\n[4]: https://github.com/python-boltons/cc-python\n[5]: https://github.com/cookiecutter/cookiecutter\n[6]: https://docs.readthedocs.io/en/stable/\n[7]: https://github.com/bbugyi200/zorg/blob/master/CONTRIBUTING.md\n[8]: https://github.com/bbugyi200/zorg\n[9]: https://pip.pypa.io\n[10]: http://docs.python-guide.org/en/latest/starting/installation/\n[11]: https://github.com/pypa/pipx\n[12]: https://github.com/cruft/cruft\n[13]: https://github.com/bbugyi200/zorg/issues/new/choose\n[14]: https://pypi.org/project/cogapp/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbugyi200%2Fzorg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbugyi200%2Fzorg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbugyi200%2Fzorg/lists"}