dahu / Bisectly

Bisectly

Quickly Locate Faulty Plugins

Bisectly is a plugin-manager-agnostic fault-localisation tool for finding which Vim plugin is causing you nose-bleeds.

Usage

.Manual Operation

Use this if you want to manually test every activated Vim instance by
hand. See the Automated Operation for using a fixed command or script
to automate the hunt.

Start Vim normally and then type `:Bisectly`.

You will be presented with a fresh instance of Vim. Test if your
problem still exists. If it does, type `:Zombies` to signify your
disgust and frustration with this hellish affliction. If the problem
has magically vanished then type `:Unicorns` and watch them dance gaily
in the fields with wild abandon. Of course, for the morbidly lazy or
chronically serious, these two commands can be more simply entered as
`:Z` and `:U` respectively.

This process will repeat several times over as your plugin set is
whittled down in pursuit of the culprit behind your woes. Hopefully
the fault exists in a single plugin. If so, Bisectly should be able to
tell you which one that is. If you answer `:Unicorns` all the way
through, then Bisectly will complain that there was no fault found.
You might want to reconsider your tests or the consistency with which
you applied them if you get this message.

Note that this will not work in gVim. You must use Vim in a terminal.
If you use gVim, it will appear to hang when you run `:Bisectly`,
because you can’t see the fresh instance of Vim that was launched.

.Automated Operation

1. Using an inline expression:

  :Bisectly if exists(':Tabularize') | Zombies | else | Unicorns | endif

2. Using a test script:

  :Bisectly so f-jumps-over-lines.vim
+
This will execute the script `f-jumps-over-lines.vim` in every test
instance, reporting that the ``faulty'' plugin is vim-fanfingtastic
(if you have it installed). The test script should call `:Unicorns`
and `:Zombies` as appropriate. Here, _appropriate_ means `:Zombies`
when the behaviour is present, `:Unicorns` without -- despite your
aesthetic take on the issue. See the `f-jumps-over-lines.vim` and
`View_command.vim` scripts in the Bisectly release for examples.

Binary Search Fault Location (BSFL)

By default, :Bisectly uses binary search (space partitioning) to quickly reduce the number of test cases it has to perform to locate the fault. This usually works well, but the algorithm can result in occasional spurious misses or hits. A slower but more thorough linear search is available with the :LSFL command. It has the same interface as its :Bisectly counterpart. For completeness, :BSFL is a synonym for :Bisectly.

Weird Things

Because Bisectly disables clumps of your `'runtimepath'` at each turn,
you might occasionally get some spurious error messages or warnings as
the Vim instance starts. These messages can be caused by complaining
plugins that are missing part of their own architecture (their
mainline code is loaded, say, but their `/after/` code was excised from
this run) or a plugin they depend on.

One thing to keep an eye out for in your tests is a change in the
negative-test behaviour. For instance, you know your tests behave a
certain way when the bug you're hunting is not present. You know
when it is present, clearly. After a few iterations like this, be
conscious of new and different messages or failures or responses that
superficially look like a negative-hit, but might indicate that your
bug is _trying_ to activate but can't because a dependent plugin is
missing. In that case, incorrectly responding with `:Unicorns` here will
result in Bisectly ultimately telling you that it couldn't locate a
fault, or worse, misrepresenting the origin of the fault.

Happy hunting.