Try to line up tab header with columns.

[profile.git] / .vim / doc / gitv.txt

gitv -- gitk for vim.

AUTHOR:   Greg Sexton <gregsexton@gmail.com>                      *gitv-author*
WEBSITE:  http://www.gregsexton.org/portfolio/gitv/
LICENSE:  Same terms as Vim itself (see :help license).
NOTES:    Much of the credit for gitv goes to Tim Pope and the fugitive plugin
          where this plugin either uses functionality directly or was inspired
          heavily.

gitv                                                                     *gitv*

1. Introduction              |gitv-introduction|
2. Installation              |gitv-installation|
3. Usage                     |gitv-usage|
4. Configuration Options     |gitv-config-options|
5. Changelog                 |gitv-changelog|
6. Misc                      |gitv-misc|

==============================================================================
1. Introduction                                             *gitv-introduction*

|gitv| is a 'gitk clone' plugin for the text editor Vim. The goal is to give
you a similar set of functionality as a repository viewer. Using this plugin
you can view a repository's history including branching and merging, you can
see which commits refs point to. You can quickly and easily view what changed
to which files and when. You can perform arbitrary diffs (using Vim's
excellent built in diff functionality) and you can easily check out whole
commits and branches or just individual files if need be.

Throw in the fact that it is running in Vim and you get for free: the ability
to move over repository history quickly and precisely using Vim's built in
movement operators. You get excellent code syntax highlighting due to Vim's
built in ability. You can open up all sorts of repository views in multiple
windows and position them exactly how you like. You can take advantage of
Vim's registers to copy multiple fragments of code from previous commits. The
list goes on.

This plugin is an extension of the |fugitive| plugin.

I hope you like it!

==============================================================================
2. Installation                                             *gitv-installation*

Install in ~/.vim, or in ~\vimfiles if you're on Windows. This plugin should
be fully pathogen compatible if you want to install it this way.

|gitv| was developed against Vim 7.3 but earlier versions of Vim should work.
Vim 7.2+ is recommended as it ships with syntax highlighting for many Git file
types. You will also need the |fugitive| plugin installed and working for
|gitv| to work.

==============================================================================
3. Usage                                                           *gitv-usage*

|gitv| defines the following command.

:Gitv[!] [args]   Invoking this command on a buffer that belongs to a git
                  repository causes the gitv browser to open. '!' causes gitv
                  to open in file mode rather than browser mode. Any [args]
                  supplied are passed on to the gitv viewer and can be used to
                  narrow the commits that are shown. If this command is run
                  on a buffer not belonging to a git repository a message
                  stating 'Not a git repository.' is displayed.

The following abbreviation is also defined so that you can type :gitv without
capitalisation.
>
    cabbrev gitv Gitv
<

3.1 Browser mode

|gitv| has two distinct modes. Browser mode and file mode. The browser mode is
opened in a new tab and allows the repository history to be viewed for all
files. This is activated by running :Gitv without a '!'.

In this mode you can view the entire repository history and see which files
were changed with each commit. This mode tries to closely resemble gitk.

3.2 File mode

File mode is opened in a |preview-window| above the buffer you are currently in.
This view is tailored to act on the buffer that :Gitv! was run from, the
"focused" file. Whilst in this mode all actions performed are specific to the
single focused file. The browser only shows commits where the focused file
changed.  Selecting a commit, views the focused file as it was in that commit.
Performing a check out only checks the focused file out as it was in the
commit. And so on. See 3.4 for the differences.

3.3 Arguments

You can pass arguments to the :Gitv command. These allow you to filter and
narrow the commits shown. Essentially, gitv is a glorified 'git log' wrapper
and so any flag that 'git log' accepts so will gitv. gitv does not inspect the
arguments passed on to 'git log' and so may not work if they don't make sense.

Without any arguments gitv behaves just like gitk and git log without
arguments. It will display the commit history for the currently checked out
branch.

Here are some particularly useful examples of arguments that could be
passed to :Gitv. For more info see 'git help log' and in particular the
section: "Commit Limiting".

    Flag              Description ~

    --all             View repository history for all refs.

    <since>..<until>  Show only commits between the named two commits. When
                      either <since> or <until> is omitted, it defaults to
                      HEAD, i.e. the tip of the current branch. For a more
                      complete list of ways to spell <since> and <until>,
                      see gitrevisions(7).

    --merges          View only merge commits.

    -S<string>        Look for differences that introduce or remove an
                      instance of <string>. Note that this is different than
                      the string simply appearing in diff output; see the
                      pickaxe entry in gitdiffcore(7) for more details.

    -G<regex>         Look for differences whose added or removed line
                      matches the given <regex>.

3.4 Key mappings.

This is a list of key mappings that will work only in the gitv browser window.
Where appropriate the differences in action is described for the two modes.

    Mode        Map     Description~

    normal      <cr>    Opens a commit. In browser mode this will show the
                        commit header information including the commit
                        message. It will also dispaly a full diff showing all the
                        changes to files.

                        Tip: if you press <cr> on anything sensible you can
                        view the expected output. For example pressing <cr> on
                        the line beginning a file diff, it will display the
                        diff using Vim's built in diff viewing capability.
                        Pressing <cr> on the tree sha will list all the files
                        in the commit and pressing <cr> on one of these will
                        show that file as it was in the commit. And so on.

                        Pressing <cr> on the line "-- Load More --" will load
                        |g:Gitv_CommitStep| more commits.

                        In file mode this will open the focused file as it was
                        in the currently selected diff. This allows you to
                        easily go back in time and look at the focused file.

                        Pressing <cr> on the top line in file mode opens the
                        current working copy of the focused file.

    normal      o       The same as <cr> but opens in a new |split|.
    normal      O       The same as <cr> but opens in a new |tab|.
    normal      s       The same as <cr> but opens in a new |vsplit|.

    normal      <c-cr>  This performs the same thing as <cr> in browser mode.
                        In file mode it opens the commit details rather than
                        the focused file.

    normal      q       Quits gitv. In browser mode this will close the entire
                        tab. In file mode this closes only the |preview-window|.
                        Note: in browser mode this will close the tab
                        regardless of any windows you may have opened as well
                        as the gitv windows.

    normal      u       Forces an update of the content of the browser window.

    normal      co      Performs a 'git checkout' of the commit the cursor is
                        on. In both modes this will present you with a choice
                        of whether you would like to checkout the sha or any
                        ref that might point to this commit.

                        File mode differs in that it doesn't check out the
                        entire commit but just the focused file in that
                        commit.

                        Tip: in gVim this will present you with a pop up dialog.
                        You can make this a text choice by performing ':set
                        guioptions+=c.'

    normal      D       Performs a diff using Vim's built in diff viewing
                        capabilities. This does nothing in browser mode. In
                        file mode it will diff the current file with the
                        focused file in the commit under the cursor.

    visual      D       In visual mode this performs a diff against the file
                        in the commit at the top of the selection against the
                        file in the commit at the bottom of the selection. The
                        newest file is always on the right.

    normal      S       This works for both browser and file mode. It opens a
                        diffstat of everything that has changed since the
                        commit under the cursor.

    visual      S       In visual mode this works in exactly the same way as
                        normal mode. However, it only shows what has changed in
                        the range of commits that are highlighted.

Here is a list of extra key mappings that can be used to efficiently move
around a repository history in the browser window.

    Mode        Map     Description~

    normal      x       Jumps the cursor forward to the next branching point
                        in the history.

    normal      X       Jumps the cursor backward to the previous branching
                        point in the history.

    normal      r       Jumps the cursor forward to the next ref in the
                        history.

    normal      R       Jumps the cursor backward to the previous ref in the
                        history.

    normal      P       Jumps the cursor to the commit referenced by HEAD.

3.5 Commands

Running the |:Git| command in the commit browser window, in either mode, will
cause the |:Git| command to be run as expected but the commit history will
automatically update to reflect any changes too.

3.6 Windows

In browser mode, two windows are opened initially. The "browser window" that
displays the commit history and the "preview window" that shows the currently
selected commit.

In file mode, a |preview-window| is opened above the current file. This is a
browser window filtered to show commits only affecting the focused file. The
window holding the focused file acts as the preview window in this mode.

NOTE: In both modes the buffer in the preview window is wiped after replacing
it.  This is to stop the quick build up of fugitive buffers. A buffer will not
be wiped if it contains unsaved changes. Buffers are not wiped when opening a
commit in a split, vsplit or a new tab.

When opening a commit, the window it will be opened in is determined by simple
rules. If in browser mode and the layout is vertical it will open in the
window to the immediate right (exactly as if you performed <c-w>l). If in a
horizontal layout, it will be opened in the window immediately below (exactly
as if you performed <c-w>j). If in file mode, it will open exactly like
browser mode split horizontally. NOTE: It is for this reason that you should
not move the browser window as it will cause commits to be opened in
unexpected places.

3.7 Folding

Folding of branches is supported in the browser window. Initially all folds
are always open and will open on a reload. You can collapse any branch by
using Vim's built in fold operators. See |folding| for more details.

==============================================================================
4. Configuration Options                               *gitv-config-options*

You can set the following options in your .vimrc to override the values used
by |gitv|. The defaults are shown.

4.1 Commit Step

This is the number of commits to show each time. When pressing <cr> on
"-- Load More --", the number of extra commits loaded is g:Gitv_CommitStep.
The default is a screen's worth of lines. This should be set to an integer
number. Setting this to a value _really_ high will load the entire repo in one
go.
>
    g:Gitv_CommitStep = &lines
<

4.2 Open Horizontal

This is the default layout to use in browser mode. If set to 0 then browser
mode will open in a vertical split. If set to 1 then browser mode will open in
a horizontal split. If set to 'auto' then browser mode will open in a vertical
split unless the content fits better in a horizontal split, in which case it
will open horizontally.

The commit browser width and height is automatically sized to best fit the
content in all modes and settings.
>
    g:Gitv_OpenHorizontal = 0
<

4.3 Git Executable

This is the name of the git executable to use to run commands. This should be
a string.
>
    g:Gitv_GitExecutable = 'git'
<
4.4 Wipe All on Close

This option should be set to either 0 (to disable) or 1 (to enable). If set to
1 then on closing the browser mode by using the q key all buffers displayed in
a window in the tab will be wiped before the tab is closed. This option allows
you to limit the number of fugitive buffers that accumulate in the use of gitv.

NOTE: This will not wipe any buffer with unsaved content. It will however
mercilessly wipe all buffers in the tab regardless of the file they hold.
>
    g:Gitv_WipeAllOnClose = 0
<

4.5 Wrap Lines

If set to 1 then line wrapping is enabled. This is useful if you have
occasional very long commit messages.
>
    g:Gitv_WrapLines = 0
<

4.6 Truncate Commit Subjects

If set to 1 then commit subject truncation is enabled. This will truncate
commit subjects, where necessary, so that the whole line will fit in one
screen width. If this is set, then automatically switching to a horizontal
layout will no longer work as commits will be truncated to always fit in a
vertical split. NOTE: It is possible that this can truncate any refs pointing
at a commit. In this situation it will not be possible to check out any of
these refs. This is due to gitv being unable to recognise that they are refs.
>
    g:Gitv_TruncateCommitSubjects = 0
<
==============================================================================
5. Changelog                                                *gitv-changelog*

1.0         First release. I hope you enjoy gitv!

==============================================================================
6. Misc                                                          *gitv-misc*

6.1 Tips and tricks

I use the following mappings to make working with |gitv| easier.
>
    nmap <leader>gv :Gitv --all<cr>
    nmap <leader>gV :Gitv! --all<cr>
<

The following abbreviation makes running arbitrary git commands much easier.
>
    cabbrev git Git
<

The function: 'Gitv_OpenGitCommand(command, windowCmd)' is provided to allow
the more advanced user to create their own commands. This function will
execute the git command provided in the new window created using windowCmd.

By using this function you get for free: the buffer set up for read only git
output, including syntax highlighting and many other tailored options. You
also get mappings for 'u' to update the output and 'q' to easily close the
window.

Here is an example of getting diff output both cached and not, in a vertical
and horizontal split respectively.
>
    call Gitv_OpenGitCommand("diff --no-color --cached", 'vnew')
    call Gitv_OpenGitCommand("diff --no-color", 'new')
<

I like my diff colors to be green for added lines and red for removed lines,
just like in the shell. Adding this to your vimrc will accomplish this.
>
    highlight diffAdded guifg=#00bf00
    highlight diffRemoved guifg=#bf0000
<

I highly recommend adding to your vimrc:
>
    set lazyredraw
<

This stops Vim from redrawing the screen during complex operations and results
in much smoother looking plugins.


6.2 Bugs, issues, features and contributing.

There are no known bugs. Hopefully there are not too many unknown. Please see
below to help.

Bugs, suggestions, pull requests and patches are all very welcome. If you find
issues with |gitv| please add them to the issues page on the github project.
Anything else, feel free to email me: gregsexton@gmail.com.

 vim:tw=78:ts=8:ft=help:norl: