This is an elisp library for org-mode, adding the ability to reference and open projects. A project is anything with a name and a directory. The Projectile package is not needed, although this package can optionally work with it.

This is not related to the other org-project, which organizes todo-items from a project into a single org-file. Renaming this project will happen once I find a reasonable alternative. Suggestions welcome.

To use, you have to first configure org-project-list-funcs with a list of methods to find project locations. For example, if you have projects in $HOME/src/ and $HOME/Dropbox/src/, you would configure org-project-list-funcs like this:

(setq org-project-list-funcs
      '((directory "~/src/")
        (directory "~/Dropbox/src/")))

The following methods are available:

• directory: Each subdirectory will be a project. Takes as an argument the parent directory to use.
• projectile: Uses the results of (projectile-relevant-known-projects). Does not take any arguments.

You also need to set up the integration with org mode, so org-mode can select from the projects found via org-project-list-functs when setting the project for a heading. To do that, add the following:

(org-project-setup)

By default, once the project is set in a heading, anywhere underneath the heading, you can call org-project-open. It is useful to have this set to a key.

(add-hook 'org-mode-hook
          (lambda () (define-key org-mode-map "\C-c o" 'org-project-open)))

When this is called, by default, the following actions happen:

1. If persp-mode is available, open a new perspective with the name of the project.
2. Open an eshell buffer in the directory of the project.
3. Create an indirect org buffer narrowed to the heading with the project.

These are configured by org-project-open-funcs, with a list of symbols. If you want to change the configuration to not open an eshell buffer, here’s an example of how to do it:

(setq org-project-open-funcs '(persp org-buffer))

The following symbols are available:

• persp: Open a perspective with the name of the project.
• eshell: Open an eshell in the directory of the project.
• org-buffer: Open a new indirect org buffer narrowed to the project heading.

If you need additional ways to find projects, you can add new methods by adding a function with the name prefixed by org-project-list-. Then you can refer to this with the method name, minus the prefix, in org-prefix-list-funcs. For example,

(defun org-project-list-mymethod (dir)
  ...
  )

(setq org-project-list-funcs '((mymethod "~/src")))

The function is expected to return a list of project name and directory conses.

Similarly, if you need additional actions to happen when opening the project, you can add a function prefixed by org-project-open-, and refer to the non-prefixed function name in org-project-open-funcs. An example:

(defun org-project-open-mymethod (name dir)
  ...)

(add-to-list 'org-project-open-funcs 'mymethod)