Merge branch 'v2'

Author: rbong

.github/workflows/test.yml

@@ -8,45 +8,26 @@ jobs:
       matrix:
         include:
           - vim_type: "Vim"
-            vim_version: "v8.2.2277"
-            vspec_vim: "vim"
+            vim_version: "v8.2.4212"
+            lua_version: "luajit-2.1.0-beta3"
+            nvim: "false"
           - vim_type: "Neovim"
             vim_version: "stable"
-            vspec_vim: "nvim"
+            nvim: "true"
     steps:
       - name: "checkout"
         uses: "actions/checkout@v2"
         with:
           fetch-depth: 5
+      - name: "install lua"
+        uses: "leafo/[email protected]"
+        with:
+          luaVersion: "${{ matrix.lua_version }}"
+        if: "${{ matrix.lua_version }}"
       - name: "install ${{ matrix.vim_type }}"
         uses: "thinca/action-setup-vim@v1"
         with:
           vim_version: "${{ matrix.vim_version }}"
           vim_type: "${{ matrix.vim_type }}"
-      - name: "install ruby"
-        uses: "ruby/setup-ruby@v1"
-        with:
-          ruby-version: "3.0"
-          bundler-cache: true
       - name: "run tests"
-        run: |
-          ${{ matrix.vspec_vim }} --version
-          script -qec " VSPEC_VIM=${{ matrix.vspec_vim }} rake test"
-  lint:
-    runs-on: "ubuntu-18.04"
-    steps:
-      - name: "checkout"
-        uses: "actions/checkout@v2"
-      - uses: actions/setup-python@v2
-        with:
-          python-version: "3.x"
-      - name: "run vint"
-        # Must remove syntax before linting
-        # https://github.com/vim-jp/vim-vimlparser/issues/98
-        # Must remove tests before linting
-        # https://github.com/Vimjas/vint/issues/330
-        run: |
-          sudo python3 -m pip install vim-vint
-          sed -i 's/^syntax .*//' syntax/floggraph.vim
-          rm -rf t/
-          vint --color .
+        run: "NVIM=${{ matrix.nvim }} ./t/run.sh"

.gitignore

@@ -1,2 +1,2 @@
 tags
-.vim-flavor
+.test

CONTRIBUTING.md

@@ -1,16 +1,25 @@
 # Contributing
 
 The idea behind this plugin is to provide a fully featured Vim branch viewer as light as possible.
-Take advantage of Vim and fugitive's builtin features instead of recreating them.
+Take advantage of Vim and Fugitive's builtin features instead of recreating them whenever possible.
 Let users customize how they use Flog so they can use their personal workflows and preferred interface.
 
 ## Running Tests
 
-Ensure you have `ruby` installed and run `rake test`.
-Tests are located at `t/*.vim` and use [vim-flavor](https://github.com/kana/vim-flavor).
+**Vim**:
+
+```
+./t/run.sh
+```
+
+**Neovim**:
+
+```
+NVIM=true ./t/run.sh
+```
 
 ## Pull Request Process
 
 1. Ensure changes to the code are simple, iterative, and consistent.
-2. Run [vint](https://github.com/Kuniwak/vint) in the root directory and make any necessary changes.
-3. Keep documentation easy to read, concise, and up-to-date.
+2. Keep documentation easy to read, concise, and up-to-date.
+3. Add/update tests if appropriate.

EXAMPLES.md

@@ -2,82 +2,91 @@
 
 ## Checking Out a Branch
 
-1. Launch the graph with `:Flog` (if this runs slowly for you, see [FAQ](FAQ.md)).
-2. Make sure your commit is in the graph by pressing `a` to toggle showing all commits.
-3. Navigate to your branch. There are a few ways to do this:
-  - Use builtin VIM navigation like `/`, `j`, `k`, etc.
+1. Open the git branch graph with `:Flog` (if this runs slowly for you, see [FAQ](FAQ.md)).
+2. Make sure your commit is in the git branch graph by pressing `a` to toggle showing all commits.
+3. Navigate to your branch. There are a couple ways to do this:
+  - Use builtin Vim navigation like `/`, `j`, `k`, etc.
   - Use `]r`/`[r` to jump between commits with refs.
-  - Use `:Flogjump` to jump towards the commit with completion.
 4. Checkout the branch. There are also a few ways to do this:
-  - Use `:Floggit checkout <Tab>`. This will complete the commit name.
-  - Use the `git` mapping to prepopulate the command line with `:Floggit<Space>`, or use `co<Space>` for `:Floggit checkout<Space>`.
   - Use `cob` to checkout the first local branch name, or remote branch if it is not available.
-  - Use `cot` to checkout the first branch name, setting it up to be tracked locally if it is a remote branch.
+  - Use `col` to checkout the first branch name, setting it up to be tracked locally if it is a remote branch.
+  - Use `:Floggit checkout <Tab>`.
+    - Use the `git` mapping to prepopulate the command line with `:Floggit`, or use `co<Space>` for `:Floggit checkout<Space>`.
+    - Using `:Floggit` lets you use completion for:
+      - Options for git commands.
+      - Git objects.
+      - Contextual Flog items, such as branch names on the current line.
 
 ## Adding Default Arguments
 
-Put this inside of your `.vimrc` to always launch Flog with the `-all` and `-max-count=2000` options:
+Put this inside of your `.vimrc` to always launch Flog with the `-no-merges` and `-max-count=2000` options:
 
 ```vim
-let g:flog_default_arguments = {
+let g:flog_default_opts = {
             \ 'max_count': 2000,
-            \ 'all': 1,
+            \ 'merges': 0,
             \ }
 ```
 
-You can use `:Flogsetargs` after the graph has launched to override these options:
+You can use `:Flogsetargs` after the git branch graph has launched to override these options:
 
 ```
 # Clear the max count
 Flogsetargs -max-count=
 # Increase the max count to 3000
 Flogsetargs -max-count=3000
+# Remove -no-merges
+Flogsetargs -merges
 # Clear out options
 Flogsetargs!
 ```
 
-If you don't want options to be cleared when you run `:Flogsetargs!` you can use `g:flog_permanent_default_arguments`.
+If you don't want options to be cleared when you run `:Flogsetargs!` you can use `g:flog_permanent_default_opts`.
 For example, if you want to always use the short date format:
 
 ```vim
-let g:flog_permanent_default_arguments = {
+let g:flog_permanent_default_opts = {
             \ 'date': 'short',
             \ }
 ```
 
 ## Diffing Commits
 
 There are several different ways to diff commits after launching Flog:
-  - Press `dd` in normal mode to diff the commit under the cursor.
-  - Visually select the commits and use `:Floggit diff <Tab>` to complete the commits at the beginning and end of the selection.
+  - Press `dd` in normal mode to diff the commit under the cursor with `HEAD`.
+  - Visually select the commits and use `:Floggit -s diff <Tab>` to complete the commits at the beginning and end of the selection.
   - Press `dd` in visual mode to diff the commits at the beginning and end of the selection
+  - Press `d!` to diff the commit at the cursor and the commit that was previously opened with `<CR>`.
 
 ## Extension Example: Switch Diff Order
 
-Instead of trying to provide settings for everything, Flog provides utility functions for customization.
+Flog has functions that allow you to easily define your own mappings and commands.
 This example shows how to switch the order of commits when diffing with `dd`.
 
 Put this code inside of your `.vimrc`:
 
 ```vim
-augroup flog
-  autocmd FileType floggraph nno <buffer> dd :<C-U>call flog#run_tmp_command('vertical belowright Git diff HEAD %h')<CR>
-  autocmd FileType floggraph vno <buffer> dd :<C-U>call flog#run_tmp_command("vertical belowright Git diff %(h'>) %(h'<)")<CR>
+augroup MyFlogSettings
+  autocmd FileType floggraph nno <buffer> dd :<C-U>exec flog#Format('vertical belowright Floggit -s -t diff HEAD %h')<CR>
+  autocmd FileType floggraph vno <buffer> dd :<C-U>exec flog#Format("vertical belowright Floggit -s -t diff %(h'>) %(h'<)")<CR>
 augroup END
 ```
 
-`flog#run_tmp_command` tells flog to run the command and treat any windows it opens as temporary.
-You can also use `flog#run_command`, which runs a command using the same syntax without temporary windows.
+`Floggit` runs a command using Fugitive's `Git` command.
+The `-s` flag prevents the Flog buffer from updating after running the command.
+The `-t` flag treats any windows it opens as temporary side windows.
 
-This function can use different special format specifiers, similar to `printf()`.
-In this case, `%h` will resolve to the hash on the current line, and `%(h'>) %(h'<)` will resolve to the hashes at the end and beginning of the visual selection.
+The `flog#Format()` function uses special format specifier items, similar to `printf()`, to get contextual information from Flog.
+
+The `%h` format specifier item used here will resolve to the hash on the current line.
+`%(h'>) %(h'<)` will resolve to the hashes at the end and beginning of the visual selection.
 
 When diffing with `dd`, Flog will now show a diff from bottom-to-top, instead of top-to-bottom.
-This is because `%(h'<)` and `%(h'>)` have been swapped from the default command.
+This is because `HEAD`/`%h` have been swapped in normal mode from the default command, and `%(h'<)`/`%(h'>)` have been swapped in visual mode.
 
 See `:help flog-command-format` for more format specifiers.
 See `:help flog-functions` for more details about calling command functions.
-You can also view [the floggraph filetype script](https://github.com/rbong/vim-flog/blob/master/ftplugin/floggraph.vim), which effectively serves as further examples of Flog's utility functions.
+You can also view [the floggraph filetype script](https://github.com/rbong/vim-flog/blob/master/ftplugin/floggraph.vim), which contains more examples.
 Finally, if you would like to view user-created commands, check out the [Wiki](https://github.com/rbong/vim-flog/wiki/Custom-Commands).
 
 ## Additional Examples
@@ -91,5 +100,5 @@ Here are some brief ideas.
 - You can start/manage a bisect with `:Floggit` commands, taking advantage of completion, and toggle seeing the current commits in the bisect with `gb`.
 - You can view the history of a file next to the file itself with `:Flogsplit -path=%`.
 - You can view the history for a particular range of lines in a file by visually selecting it and then typing `:Flog`.
-  This will display an inline patch, which you can trigger with `gp`.
-- If you haven't already, look through `:help flog`. There are many commands that still haven't been covered here.
+  - This will display an inline patch, which you can trigger with `gp`.
+- If you haven't already, look through `:help flog`. There is much that still hasn't been covered here.

FAQ.md

@@ -2,102 +2,80 @@
 
 ## How do I get Flog to run faster?
 
-There are several ways to get Flog to run faster depending on what your exact issue is.
+The answer depends on your issue.
 
-**Specifying the max count**
+**Flog is slow the first time it runs for a repo**
 
-You may want to specify `-max-count=<count>`, or use `let g:flog_default_arguments = { 'max_count': <count> }`.
+The first time Flog runs for a repo, it runs `git commit-graph write`.
+This ultimately makes it run faster.
 
-This restricts the log to displaying a certain number of commits.
-This will increase the speed at which Flog can redraw the commit graph, generally reducing lag.
-
-If you need to jump forward/backwards in history by `<count>`, use `[[`/`]]`
-
-**Pre-calculating the commit graph**
-
-In very large repositories, the commit graph can take a long time to sort when you use `git log --graph` or run Flog, even with max count specified.
-In these cases you can pre-calculate the commit graph.
-
-If you are running Git 2.24 or greater, it is enabled by default.
-Otherwise it can be enabled via:
+Disable this feature:
 
 ```
-git config --global core.commitGraph true
-git config --global gc.writeCommitGraph true
+let g:flog_write_commit_graph = 0
 ```
 
-After that, navigate to your repository and run `git commit-graph write`.
-
-This command may still take a long time to run, but once it has been generated, `git log --graph` and Flog will run much faster.
-If you don't plan to view a large number of commits that aren't reachable, you can use `git commit-graph write --reachable` to speed up this process.
+Set args (defaults shown):
 
-You may want to re-run this command regularly when there are enough new commits.
-
-**Disabling graph mode**
-
-If you want to skip generating a graph and use Flog just as a log viewer, you can pass `-no-graph` to Flog or use the `gx` binding to toggle the graph.
-This is equivalent to `git log --no-graph`.
-
-If this is still too slow, it might be because Flog has to wait until the command completes to write output to the buffer.
-In these cases, you may want to resort to just using `git log` in the terminal.
+```
+let g:flog_write_commit_graph_args = '--reachable --progress'
+```
 
-**Flog is still too slow**
+**Flog gets slower over time for repos**
 
-Flog, unlike other branch viewers like `gitk`, is just a wrapper around `git log`.
-It just reads static output from the command after it finishes and writes it to a buffer.
-By contrast, `gitk` reads raw commit data, calculates the graph structure itself commit-by-commit, and updates the display, all without hanging.
+The commit graph will eventually become out of date.
 
-This may change in the future, so check back.
+You can update it by running:
 
-If you have any feedback about Flog's speed or any of the suggestions above, please see [this ongoing issue](https://github.com/rbong/vim-flog/issues/26).
+```
+git commit-graph write --reachable --progress
+```
 
-## How do I get Flog to look nicer?
+**Flog takes a long time to load for many commits**
 
-Flog struggles with highlighting since Vim is not built to highlight vertical columns.
+By default, Flog will shows 5,000 commits.
 
-To use the same highlighting that `git log --graph` would use in the shell,
-[download the AnsiEsc.vim plugin](https://github.com/vim-scripts/AnsiEsc.vim),
-then add `let g:flog_use_ansi_esc = 1` to your `.vimrc`.
+Launch with less commits:
 
-Note that using `AnsiEsc.vim` with Flog comes with a performance hit.
+```
+:Flog -max-count=2000
+```
 
-Another option is to use a custom command to replace `git log --graph`.
-Some users prefer the look of [git-forest](https://github.com/rbong/git-scripts/blob/master/git-forest),
-pictured below.
+Launch with less commits by default:
 
-![git-forest](img/git-forest.png)
+```
+let g:flog_permanent_default_opts = { 'max_count': 2000 }
+```
 
-To use `git-forest` as a custom log command,
-[download it from here](https://github.com/rbong/git-scripts/blob/master/git-forest),
-and add it to your path, then add this to your `.vimrc`.
+**Flog takes a long time to load for complex git branch graphs**
 
-```vim
-let g:flog_build_log_command_fn = 'flog#build_git_forest_log_command'
-```
+Toggle the graph with `gx` or launch with `:Flog -no-graph`.
 
-## Why not just use the `git log --graph` command?
+**Other issues**
 
-To interact with commits.
+Please [post an issue](https://github.com/rbong/vim-flog/issues/).
 
-## Why have a branch viewer inside of Vim?
+## What are the differences with other branch viewers?
 
-This allows seamlessly switching between navigating the commit history, running git commands, and editing files checked into git.
+[gv.vim](https://github.com/junegunn/gv.vim) is an ultra-light branch viewer.
 
-It also prevents having to learn another git interface on top of [fugitive](https://github.com/tpope/vim-fugitive).
+[gitv](https://github.com/gregsexton/gitv) is a fully featured branch viewer.
 
-If you want to know everything you can do with fugitive, I recommend [the Vimcasts fugitive series](http://vimcasts.org/blog/2011/05/the-fugitive-series/).
+Flog is faster than gitv.
+Flog is slower than gv.vim, but in many cases only marginally.
 
-## What are the differences with other branch viewers?
+gv.vim and gitv rely on the output of `git log --graph`.
+Flog draws the git branch graph itself.
+This allows for branch highlighting and beautiful git branch graphs.
 
-[gv.vim](https://github.com/junegunn/gv.vim) is an ultra-light branch viewer, whereas Flog is fully featured.
-Flog allows updating the graph, running commands, and customization, where gv does not.
+Flog is more customizable and flexible than gitv.
+gv.vim does not have any customization or flexibility by design.
 
-[gitv](https://github.com/gregsexton/gitv) is another fully featured branch viewer.
-Flog is a next generation branch viewer that learns a lot of lessons from gitv.
-It has a better defined argument system, more robust window management, more stable update system, has the ability to run more commands in the graph easier, has cleaner mappings, and supports any log format.
+Flog has features which have no equivalent in either of the other branch viewers.
+This includes commit marks, some navigation mappings, and contextually aware command completion.
 
 ## How can I learn how to use flog?
 
 See `:help flog` for all commands and options.
-See [the examples](EXAMPLES.md) for detailed walkthroughs of different operations using flog.
-Please [post an issue](https://github.com/rbong/vim-flog/issues) if you have any questions on how to do anything.
+See [examples](EXAMPLES.md) for detailed walkthroughs.
+Please [post an issue](https://github.com/rbong/vim-flog/issues) if you have any questions.