sponsor Vim development Vim logo Vim Book Ad

projectionist.vim : Granular project configuration

 script karma  Rating 16/7, Downloaded by 2135  Comments, bugs, improvements  Vim wiki

created by
Tim Pope
script type
Projectionist provides granular project configuration using "projections".  What are projections?  Let's start with an example.

## Example

A while back I went and made a bunch of plugins for working with rbenv.  Here's what a couple of them look like:

    ~/.rbenv/plugins $ tree
    |-- rbenv-ctags
    |   |-- bin
    |   |   `-- rbenv-ctags
    |   `-- etc
    |       `-- rbenv.d
    |           `-- install
    |               `-- ctags.bash
    `-- rbenv-sentience
        `-- etc
            `-- rbenv.d
                `-- install
                    `-- sentience.bash

As you can see, rbenv plugins have hooks in `etc/rbenv.d/` and commands in `bin/` matching `rbenv-*`.  Here's a projectionist configuration for that setup:

    let g:projectionist_heuristics = {
          \   "etc/rbenv.d/|bin/rbenv-*": {
          \     "bin/rbenv-*": {
          \        "type": "command",
          \        "template": ["#!/usr/bin/env bash"],
          \     },
          \     "etc/rbenv.d/*.bash": {"type": "hook"}
          \   }
          \ }

The key in the outermost dictionary says to activate for any directory containing a subdirectory `etc/rbenv.d/` *or* files matching `bin/rbenv-*`.  The corresponding value contains projection definitions.  Here, two projections are defined.  The first creates an `:Ecommand` navigation command and provides boilerplate to pre-populate new files with, and the second creates an `:Ehook` command.

## Features

See `:help projectionist` for the authoritative documentation.  Here are some highlights.

### Global and per project projection definitions

In the above example, we used the global `g:projectionist_heuristics` to declare projections based on requirements in the root directory.  If that's not flexible enough, you can use the autocommand based API, or create a `.projections.json` in the root of the project.

### Navigation commands

Navigation commands encapsulate editing filenames matching certain patterns.  Here are some examples for this very project:

      "plugin/*.vim": {"type": "plugin"},
      "autoload/*.vim": {"type": "autoload"},
      "doc/*.txt": {"type": "doc"},
      "README.markdown": {"type": "doc"}

With these in place, you could use `:Eplugin projectionist` to edit `plugin/projectionist.vim` and `:Edoc projectionist` to edit `doc/projectionist.txt`.  For `README.markdown`, since there's no glob, it becomes the default destination for `:Edoc` if no argument is given.

The `E` stands for `edit`.  You also get `S`, `V`, and `T` variants that `split`, `vsplit`, and `tabedit`.

Tab complete is smart.  Not quite "fuzzy finder" smart but smart nonetheless.  (On that note, fuzzy finders are great, but I prefer the navigation command approach when there are multiple categories of similarly named files.)

### Alternate files

Projectionist provides `:A`, `:AS`, `:AV`, and `:AT` to jump to an "alternate" file, based on ye olde convention originally established in vimscript #31.  Here's an example configuration for Maven that allows you to jump between the implementation and test:

      "src/main/java/*.java": {"alternate": "src/test/java/{}.java"},
      "src/test/java/*.java": {"alternate": "src/main/java/{}.java"}

Bonus feature: `:A {filename}` edits a file relative to the root of the project.

### Buffer configuration

Check out these examples for a minimal Ruby project:

      "*": {"make": "rake"},
      "spec/*_spec.rb": {"dispatch": "rspec {file}"}

That second one sets the default for dispatch.vim (vimscript #4504).  Plugins can use projections for their own configuration.
install details
Extract in ~/.vim (~\vimfiles on Windows).


rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
projectionist.zip 1.3 2018-09-03 7.0 Tim Pope Fix :Pcd and :Plcd.
projectionist.zip 1.2 2018-08-28 7.0 Tim Pope Support virtual buffers from plugins like Fugitive.
Minor bug fixes.
projectionist.zip 1.1 2018-07-03 7.0 Tim Pope Provide "path" projection to append to 'path'.
Add tags file to 'tags' for each project root.
Provide snakecase transformation.
Change camelcase transformation from UpperCamelCase to lowerCamelCase.
Support mods like :vertical.
Support +cmd and ++opt.
Replace :Cd and :Lcd with :Pcd and :Plcd.
Prompt to create alternate if none exists.
Bug fixes.
projectionist.zip 1.0 2014-07-21 7.0 Tim Pope Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
Vim at Github