https://github.com/cuttlefisch/declarative-project-mode
Manage and install variety of project contents with simple declatative syntax using Emacs minor mode.
https://github.com/cuttlefisch/declarative-project-mode
Last synced: about 1 month ago
JSON representation
Manage and install variety of project contents with simple declatative syntax using Emacs minor mode.
- Host: GitHub
- URL: https://github.com/cuttlefisch/declarative-project-mode
- Owner: cuttlefisch
- License: gpl-3.0
- Created: 2023-01-14T02:02:53.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-04-14T21:54:36.000Z (2 months ago)
- Last Synced: 2026-04-14T23:32:58.722Z (2 months ago)
- Language: Emacs Lisp
- Size: 215 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.org
- Changelog: CHANGELOG.org
- Contributing: CONTRIBUTING.org
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
#+TITLE: declarative-project-mode
#+HTML: 
An Emacs minor mode for declarative project resource management. Define your
project's dependencies, files, symlinks, and workspace assignments in a single
=.project= file, then install everything with one keybinding.
* Installation
** straight.el / Doom Emacs
#+begin_src emacs-lisp
;; straight.el
(straight-use-package
'(declarative-project-mode
:host github
:repo "cuttlefisch/declarative-project-mode"))
;; Doom Emacs (packages.el)
(package! declarative-project-mode
:recipe (:host github
:repo "cuttlefisch/declarative-project-mode"))
#+end_src
** Manual
#+begin_src shell
git clone https://github.com/cuttlefisch/declarative-project-mode.git
#+end_src
#+begin_src emacs-lisp
(add-to-list 'load-path "/path/to/declarative-project-mode")
(require 'declarative-project-mode)
#+end_src
* Usage
Create a =.project= file in your project root. The mode activates automatically
when you visit a =.project= file.
Press =C-c C-c i= to install all declared resources.
** Example =.project= (YAML)
#+begin_src yaml
project-name: "My Project"
required-resources:
- README.org
- src/main.el
deps:
- src: git@github.com:user/repo.git
dest: vendor/repo
- src: git@github.com:user/other.git
args: "--branch develop"
local-files:
- src: ~/templates/makefile
dest: Makefile
symlinks:
- targ: ~/notes/my-project.org
link: docs/notes.org
treemacs-workspaces:
- "Emacs Packages"
#+end_src
** Auto-install
To install resources automatically when the mode activates:
#+begin_src emacs-lisp
(setq declarative-project-auto-install t)
#+end_src
* Org-Babel Integration
Embed project specs in org files as =declarative-project= src blocks:
#+begin_example
#+begin_src declarative-project :dir ~/my-project
project-name: "My Project"
deps:
- src: git@github.com:user/repo.git
dest: repo
#+end_src
#+end_example
Execute with =C-c C-c= on the src block. The =:dir= header argument sets the
project root directory (defaults to =default-directory=).
Enable in your config:
#+begin_src emacs-lisp
(add-to-list 'org-babel-load-languages '(declarative-project . t))
(org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages)
#+end_src
* Treemacs Workspace Integration
The optional =declarative-project-treemacs-mode= manages treemacs workspaces
from =.project= files. Each project declares which workspaces it belongs to, and
the mode ensures those assignments exist.
#+begin_src emacs-lisp
(require 'declarative-project-treemacs)
(declarative-project-treemacs-mode 1)
#+end_src
When enabled, project installation creates or updates treemacs workspace
entries. Set =declarative-project-treemacs-autoprune= to =nil= to disable
automatic removal of stale project entries on mode init.
** Framework-specific configuration
*** Doom Emacs
In =packages.el=:
#+begin_src emacs-lisp
(package! declarative-project-mode
:recipe (:host github :repo "cuttlefisch/declarative-project-mode"))
#+end_src
In =config.el=:
#+begin_src emacs-lisp
(use-package! declarative-project-mode
:config
(after! treemacs
(require 'declarative-project-treemacs)
(setq declarative-project-treemacs-cache-file
(expand-file-name "treemacs-declared-workspaces.el" doom-cache-dir))
(declarative-project-treemacs-mode 1)))
#+end_src
*** Spacemacs
In =dotspacemacs-additional-packages=:
#+begin_src emacs-lisp
(declarative-project-mode
:location (recipe :fetcher github :repo "cuttlefisch/declarative-project-mode"))
#+end_src
In =dotspacemacs/user-config=:
#+begin_src emacs-lisp
(require 'declarative-project-treemacs)
(setq declarative-project-treemacs-cache-file
(expand-file-name "treemacs-declared-workspaces.el" spacemacs-cache-directory))
(declarative-project-treemacs-mode 1)
#+end_src
*** Vanilla Emacs
#+begin_src emacs-lisp
(require 'declarative-project-treemacs)
(declarative-project-treemacs-mode 1)
;; Cache file defaults to user-emacs-directory; customize if needed:
;; (setq declarative-project-treemacs-cache-file "~/.cache/emacs/treemacs-declared-workspaces.el")
#+end_src
* Spec Reference
| Field | Type | Description |
|------------------------+---------------+------------------------------------------------------|
| =project-name= | string | Display name for the project |
| =required-resources= | list(string) | Paths that must exist; warns on missing |
| =deps= | list(object) | Git repos to clone (=src=, =dest=, =args=) |
| =local-files= | list(object) | Files to copy into the project (=src=, =dest=) |
| =symlinks= | list(object) | Symlinks to create (=targ=, =link=) |
| =treemacs-workspaces= | list(string) | Treemacs workspaces to assign this project to |
For =deps=, =local-files=, and =symlinks=: omitting =dest= or =link= defaults
to placing the resource in the project root directory.
* Configuration
| Variable | Default | Description |
|--------------------------------------------+---------+---------------------------------------------------|
| =declarative-project-auto-install= | =nil= | Auto-run installation when mode activates |
| =declarative-project-treemacs-autoprune= | =t= | Remove stale project entries on treemacs mode init |
| =declarative-project-treemacs-cache-file= | =user-emacs-directory= | Path to the workspace cache file |
* Development
#+begin_src shell
cask install
make test # 96 Buttercup specs
#+end_src
See [[file:CONTRIBUTING.org][CONTRIBUTING.org]] for the full development guide.
* License
[[file:LICENSE][GNU General Public License v3.0]]