==============
Dooti overview

Manage default handlers for files and URI schemes on MacOS 12.0+.

Features

• Manage handlers by specifying file extension, UTI or URI scheme.
• Specify handlers by name, bundle ID or absolute path.
• Check your associations into a dotfiles repository and ensure an idempotent state by simply running dooti apply.

Installation

I recommend installing with pipx <https://pipx.pypa.io/stable/>_, although pip will work fine as well:

.. code-block:: bash

    pipx install dooti

Quickstart

dooti currently supports three specific subcommands (ext, scheme, uti) and a broad one (apply).

Lookup handlers

Simply pass a list of one specific type to the appropriate command. Example:

.. code-block:: console

    $ dooti ext html xml
    html: /Applications/Firefox.app
    xml: /Applications/Sublime Text.app

    $ dooti --format json scheme http https ftp | jq
    {
      "http": "/Applications/Firefox.app",
      "https": "/Applications/Firefox.app",
      "ftp": "/System/Library/CoreServices/Finder.app"
    }

    $ dooti uti public.html
    public.html: /Applications/Firefox.app

Set handlers
~~~~~~~~~~~~
Changing the default handler can be requested by adding ``-x <handler_ref>`` to the lookup command. The handler reference can be a name, bundle ID or absolute filesystem path. Example:

.. code-block:: console

    $ dooti ext csv xml -x "Sublime Text"
    The following extensions are set to be changed:
    csv: /Applications/Numbers.app -> /Applications/Sublime Text.app
    xml: /Applications/Firefox.app -> /Applications/Sublime Text.app

    $ dooti scheme ftp -x /Applications/Firefox.app
    The following scheme is set to be changed:
    ftp: /System/Library/CoreServices/Finder.app -> /Applications/Firefox.app

    $ dooti -tf json uti public.c-source -x com.sublimetext.4
    {"changes": {"utis": {"public.c-source": {"from": "/Applications/Notes.app", "to": "/Applications/Sublime Text.app"}}}, "errors": []}


Ensure state
~~~~~~~~~~~~
``dooti`` can ingest and apply a YAML configuration like this:

.. code-block:: yaml

    ext:
      jpeg: Preview

    scheme:
      http: Firefox
      mailto: Mail

    uti:
      public.c‑source: Sublime Text

    app:
      Sublime Text:
        ext:
          - py
          - rst
          - yml
          - yaml
        uti:
          - public.fortran‑source

      Brave Browser:
        scheme:
          - ipfs

By default, it looks at ``$XDG_CONFIG_HOME/dooti/config.yaml`` (and others, see ``docs/usage.rst``).

Limitations
-----------
* The designated handler has to be installed before running the command.
* Setting some URI scheme handlers (especially for http) might cause a prompt.
* Setting some file extension handlers might be restricted (especially html seems to fail silently).


Why?
----
Most existing tools use `LSSetDefaultRoleHandlerForContentType <https://developer.apple.com/documentation/coreservices/1444955-lssetdefaultrolehandlerforconten>`_ and `LSSetDefaultHandlerForURLScheme <https://developer.apple.com/documentation/coreservices/1447760-lssetdefaulthandlerforurlscheme?language=objc>`_, which are deprecated in macOS 12.0. ``dooti`` uses a more recent API and should work on Monterey (12.0) and above.


Similar tools
-------------
* `duti <https://github.com/moretension/duti>`_
* `openwith <https://github.com/jdek/openwith>`_
* `defaultbrowser <https://gist.github.com/miketaylr/5969656>`_
* `SwiftDefaultApps <https://github.com/Lord-Kamina/SwiftDefaultApps>`_