vim-projectionist

Projections allow you to define granular project configurations. You can define them globally using g:projectionist_heuristics in your Vim configuration, via an autocommand-based API, or by creating a .projections.json file in the root of your project.

Projections can define several types of behaviors, such as navigation commands, alternate files, and buffer configurations.

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

You can define an alternate relationship between files. This allows you to jump between related files (like implementation and test files) using the :A command family.

Commands:

• :A (alternate)
• :AS (alternate split)
• :AV (alternate vsplit)
• :AT (alternate tabedit)

Example Configuration: In this example, jumping from a Java source file will take you to its corresponding test file, and vice versa.

Bonus: :A {filename} allows you to edit a file relative to the project root.

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

Projections can be used to configure buffer-specific settings or to set default tasks for plugins like dispatch.vim.

For example, you can specify that the make command should run rake for all files, or that running a dispatch task on a spec file should use rspec with the current file passed as an argument.

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

Navigation commands encapsulate editing filenames that match specific patterns. When you define a projection with a type (like plugin, autoload, or doc), Projectionist creates navigation commands.

Commands follow the pattern E<Type>, where E stands for edit. You also have S (split), V (vsplit), and T (tabedit) variants.

Examples:

• :Eplugin projectionist edits plugin/projectionist.vim.
• :Edoc projectionist edits doc/projectionist.txt.
• If no argument is provided, the command edits an alternate file of that type or a projection without a glob (e.g., :Edoc might default to README.markdown).

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

You can install projectionist.vim using your favorite Vim plugin manager or by using Vim's built-in package support. To install manually using built-in support, run the following commands:

mkdir -p ~/.vim/pack/tpope/start
cd ~/.vim/pack/tpope/start
git clone https://tpope.io/vim/projectionist.git
vim -u NONE -c "helptags projectionist/doc" -c q