declarative-project-mode

A global minor mode for managing and installing a variety of project contents with a simple declarative syntax in Emacs. With this mode we can specify a collection of git repositories and local resources, as well as update Emacs’s state with Agenda files and workspaces using a simple YAML file.

Currently supported behavior:

• Specify target into which project installs
• Install git dependencies using HTTPS or SSH url format from Github or Gitlab
• Automatically add local project contents to Agenda, and create default agenda files
• Warn if any `required-resources` are missing
• Symlink and copy local files to project during install
• Assign project to Treemacs Declarative Workspaces

Usage

There are two supported specification formats: a YAML spec file, or the same YAML specification within an org mode source block.

Emacs Configuration Changes

With the use-package! macro:

(use-package! declarative-project-mode
  :after org
  :init
  ;; Optionally enable auto-prune to remove invalid projects without prompt when:
  ;; - Initializing the mode's setup
  ;; - Installing a new project
  (setq declarative-project--auto-prune-cache t) ;; default value is `nil'
  (declarative-project--mode-setup))

Plain YAML

To install and manage a project in plain YAML:

1. Follow Defining a Project to create the YAML spec file
2. Visit the file in Emacs with declarative-project-mode enabled
3. Run the function (declarative-project--install-project)
4. After the “Installation Finished!” message check contents of root-directory

SRC Block Embedded YAML

There is no difference in functionality between YAML in source blocks and plain YAML project definitions; define projects following the standard YAML project file instructions.

Execute the source block to install a project like the one below:

#+begin_src declarative-project
name: "Empty Project"
root-directory: /tmp/empty-project-dir
workspaces:
 - "Deleteme"
#+end_src

If using the :tangle argument the target location is cached rather than the org source file. For example, the following source block would cache the path “/tmp/project-dir/project.yaml”

#+begin_src declarative-project :tangle /tmp/project-dir/project.yaml
name: "Empty Project"
root-directory: /tmp/project-dir
workspaces:
 - "Deleteme"
#+end_src

Defining a project

Currently supported options:

name

The display name for the project to Treemacs, etc.

root-directory

The directory into which all project dependencies are installed. Any paths specified in the YAML spec are relative to root-directory for any install operations.

agenda-files

A list of files added to org-agenda-files. Installation processes these last, so installation only creates these files if they are not otherwise created (copied, symlinked, etc.). Any of these already present are added to org-agenda-files.

required-resources

A list of resources that must exist for the project to be considered complete. Installation warns if any are missing.

deps

A list of git repositories cloned into the root-directory or other dest relative to root-directory.

local-files

A list of files copied from their current location to the project directory.

symlinks

List of link/target pairs to create as symbolic links relative to the root-directory directory.

workspaces

A list of workspace names this project should be added to. Currently only supports Treemacs Declarative Workspaces.

Note that any omitted dest or link field results in that resource’s creation immediately within the project root-directory, named matching the specified source filename.extension.

Example Project source block:

name: "Declarative Project Mode"
root-directory: "/tmp/demo-project"
#                                (↑) No trailing /
agenda-files:
  - README.org
  - AGENDA.org
required-resources:
  - README.org
deps:
  - src: [email protected]:cuttlefisch/declarative-project-mode.git
  - src: [email protected]:cuttlefisch/declarative-project-mode.git
    dest: DCM
    # (↑) Creates /tmp/demo-project/DCM/
  - src: https://github.com/cuttlefisch/treemacs-declarative-workspaces-mode
local-files:
  - src: ~/path/to/src
    dest: path/to/dest
    # (↑) path relative to project root dir
  - src: /path/to/src
    # (↑) default dest is project root dir
  - src: /path/to/README.org
    dest: README.org
symlinks:
  - targ: /path/to/link-target
    link: path/to/symlink
  - targ: ~/path/to/link-target
    # (↑) default link is project root dir
workspaces:
  - "Demos"

Noteworthy Features

Decentralized Org Agenda Management

Specifying agenda-files results in those files’ addition to org-agenda-files upon project installation, and upon mode enablement. This mode caches the filepaths for any installed projects, and checks the spec files at the specified file paths for their agenda files. Any of them found are added to org-agenda-files, and if declarative-project--persist-agenda-files then missing agenda files are recreated.

This allows users to specify any relevant agenda files as they define projects, and keep this list current without additional overhead.

Org-Babel Support

Install a project via org-babel by setting the src-block language to declarative-project, and hitting Enter in the YAML block.

Persistent Project Cache

Cache installed project source locations to rebuild agenda, workspaces, and other systems across restarts.

Treemacs Declarative Workspace Assignment

Provided a list of Treemacs Declarative Workspaces, the installation process assigns this project to each specified worksace. This helps decentralize workspace configuration, helping construct conceptual groupings of projects regardless of their location in the filesystem.

Locally Copy or Symlink Resources

It’s often useful to maintain documentation in a form of knowledgebase such as Org Roam. This approach allows us to maintain a declarative set of symlinks to connect a project to the documentation, Rather than adapt the documentation & knowledge-building process to conform to individual projects.

Future Plans

• Support custom resource types & install methods
  • cloud storage backend
  • s3 backend
  • package managers
• Recursive project definitions, i.e. subprojects