From 24642a92ee5af762542fb8c5e1385f5d2693ae78 Mon Sep 17 00:00:00 2001
From: Ches Martin <ches@whiskeyandgrits.net>
Date: Sat, 7 Feb 2015 02:17:31 +0700
Subject: [PATCH] :AgBuffer fix for legacy --column users

Prior to the `--vimgrep` option being added, it was very hard to get Ag
to output file names consistently if only one file was searched rather
than multiple files or a directory [1].

This meant that if you ran an `:AgBuffer` search when you had only
opened one buffer in your Vim session, quickfix navigation would be
broken for your results.

The changed incantation of `ag` in this commit is the best behavior I
was able to get out of earlier Ag versions, after a long saga. It has
one minor drawback: it results in empty newlines between results for
different files, where a heading might otherwise be. This is a small
cosmetic problem--Vim's quickfix parses it just fine and skips over
these on `:cnext` without any glitch or extra keystrokes. This seems a
worthwhile exchange for the outright bug of the single-buffer case.

References d42171e19

[1]: https://github.com/ggreer/the_silver_searcher/issues/361
---
 autoload/ag.vim |  3 ++-
 doc/ag.txt      | 18 ++++++++++++++----
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/autoload/ag.vim b/autoload/ag.vim
index a5139d4f..6a96e3e1 100644
--- a/autoload/ag.vim
+++ b/autoload/ag.vim
@@ -22,7 +22,8 @@ if !exists("g:ag_prg")
   if split(system("ag --version"), "[ \n\r\t]")[2] =~ '\d\+.[2-9][5-9]\(.\d\+\)\?'
     let g:ag_prg="ag --vimgrep"
   else
-    let g:ag_prg="ag --column"
+    " --noheading seems odd here, but see https://github.com/ggreer/the_silver_searcher/issues/361
+    let g:ag_prg="ag --column --nogroup --noheading"
   endif
 endif
 
diff --git a/doc/ag.txt b/doc/ag.txt
index 29b8a6fc..bc9b8af7 100644
--- a/doc/ag.txt
+++ b/doc/ag.txt
@@ -19,10 +19,11 @@ the results in a split window.
     Search for {pattern} in all open buffers. Behaves just like the |:grep|
     command, but will open the |Quickfix| window for you. If [!] is not given
     the first error is jumped to.
-    Note: this will not find your changes in modified buffers (it really
-    only searches the files that match your open buffers). You can save
-    buffers automatically when searching with the 'autowrite' option. The
-    buffer will be ignored if it is an directory.
+
+    Note: this will not find changes in modified buffers, since ag can only
+    find what is on disk! You can save buffers automatically when searching
+    with the 'autowrite' option. A buffer will be ignored if it is a directory
+    (an explorer, like netrw).
 
 :AgAdd [options] {pattern} [{directory}]                               *:AgAdd*
 
@@ -80,6 +81,15 @@ The location of the Ag program, and any options you want passed to it before
 searching. Default: "ag --vimgrep" (for parsable output). Example: >
   let g:ag_prg="ag --vimgrep --smart-case"
 <
+Note: the `--vimgrep` option was added in Ag 0.25.0. If ag.vim detects that
+you're using a lower version, the following default will be used instead: >
+  let g:ag_prg="ag --column --nogroup --noheading"
+<
+This works around inconsistent behaviors in earlier Ag versions, but it is
+recommended that you upgrade if possible for a better experience. `--vimgrep`
+supports multiple matches on the same line of text, for example.
+
+For background, see: https://github.com/rking/ag.vim/pull/88
 
                                                                *g:ag_highlight*
 If 1, highlight the search terms after searching. Default: 0. Example: >