*gitlog.txt*  For Vim version 7.4

                                           
        ,----.   ,--.  ,--.  ,--.                                          ~
       '  .-./   `--',-'  '-.|  |    ,---.  ,---.                          ~
       |  | .---.,--.'-.  .-'|  |   | .-. || .-. |                         ~
       '  '--'  ||  |  |  |  |  '--.' '-' '' '-' '                         ~
        `------' `--'  `--'  `-----' `---' .`-  /                          ~
                                           `---'                           ~


Author:   Peter Antoine
Date:     Jan 20, 2017
Version:  6.0.0

HomePage: https://github.com/PAntoine/vimgitlog


For instructions on installing this file, type:
>
    :help add-local-help |add-local-help| inside Vim.
<

==============================================================================
1. Contents                                       *gitlog* *gitlog-contents*

    1. Contents...............................: |gitlog-contents|
    2. Description............................: |gitlog-description|
    3. Usage..................................: |gitlog-usage|
    4. Git History Searching..................: |gitlog-searching|
    5. Git History Tree.......................: |gitlog-tree|
    6. Mapping GitLog Functions...............: |gitlog-mapping|
    7. File Commands..........................: |gitlog-file-commands|
    8. Configuring GitLog.....................: |gitlog-config|
    9. History................................: |gitlog-history|

==============================================================================
2. Description                                   *gitlog-description*

This is a simple pure vim plugin that interfaces with git. It allows you
to simply diff different version of the file in the main window. 

This plugin tries to make access to the history the git stores easier to
access.

For details on the changes between versions see |gitlog-history|.

==============================================================================
3. Usage                                         *gitlog-usage*

GitLog expects that you are in a sub-directory of the Git repository. When
GitLog is activated it will check to see if there is a .git directory in the
path. It will error if it cannot find one. It will use this Git repository
for all operations.

The only function that really should be called outside of GitLog is the toggle
function 'GITLOG_ToggleWindows()' function. This will do (as really should be
expected) toggle the GitLog windows.

What it will display is a full-height window split into two. The top window
will have the current branch name followed by the commits on that branch. The
bottom left window will have all the local branches that are found in the 
repository.

The windows will look as follows:

       -------------------------------------------------------------------
      | branch: master     |                                              |
      | * xxxxxxx commit th|                                              |
      | * xxxxxxx commit th|                                              |
      .                    .                                              .
      .                    .                                              .
      .                    .                                              .
      |====================|                                              |
      |  branch_1 xxxxxxx s|                                              |
      |  branch_2 xxxxxxx s|                                              |
      |* branch_3 xxxxxxx s|                                              |
      |  branch_4 xxxxxxx s|                                              |
      |                    |                                              |
      |                    |                                              |
       -------------------------------------------------------------------

The '*' in the branch window represents the current branch that the repository
is on. GitLog does not change this. Internally it may list other branches but
it does not change the branch in the repository.

Gitlog supports the following keys in the Log window:

Diff Revision: <cr> or 'd'

This will diff the revision that is under the cursor. It will also set the
current revision to this commit. This means that if you switch to the tree
window then the view will be of this commit.

Search Commits: 's'

This key will cause the repository to be searched. It will ask you for the
string that you want to search for. See |gitlog-searching|.

Open Revision: 'o'

This key will cause the revision file to be opened. The commit version of
the file will be opened.

Open Revision Tree: 't'

This key will cause the revision tree to be opened at this commit.

Close Diff Buffer: <c-d>

Pressing these keys will cause the any diff windows that are open to close.

Reset Commit: <c-h>

This will reset the commit to HEAD. After some of the above commands the 
commit will change. 


==============================================================================
4. Git History Searching                                *gitlog-searching*

GitLog has the ability to allow for searching the historical commits in the
repository for text strings. GitLog allows for this to be done either on the
current selected commit or, on a selection of commits.

To search the repository in the Log Window 's' while the cursor is on a 
single commit, or use the visual selection to select a group of commits then
press 's'. GitLog will then present you with a prompt for the string that is
to be searched for. Type in the string then press return and the following
extra window will appear:

       -------------------------------------------------------------------
      | branch: master     |                                              |
      | * xxxxxxx commit th|                                              |
      | * xxxxxxx commit th|                                              |
      .                    .                                              .
      .                    .                                              .
      .                    .                                              .
      |====================|==============================================|
      |  branch_1 xxxxxxx s|xxxxxxx:filname:nn:the line from the file     |
      |  branch_2 xxxxxxx s|xxxxxxx:filname:nn:the line from the file     |
      |* branch_3 xxxxxxx s|xxxxxxx:filname:nn:the line from the file     |
      |  branch_4 xxxxxxx s|xxxxxxx:filname:nn:the line from the file     |
      |                    |xxxxxxx:filname:nn:the line from the file     |
      |                    |xxxxxxx:filname:nn:the line from the file     |
       -------------------------------------------------------------------

This extra window shows files that have been found in the search with the
commits that they belong to. This window now works in the same way as the
log window, that is if you press '<cr>' the file that is selected will be
diff'ed against the same file in the current repository. If 'o' is selected
then the selected revision of the file will be opened along side the current
file in the window.

The search windows can be pulled down with the rest by toggling the GitLog
windows.

==============================================================================
5. Git History Tree                                *gitlog-tree*

GitLog has the ability to allow to display the selected commit in a tree format.
This will be a tree of the current repository. It will open and select the 
current file in the tree.

It will let you navigate the tree either by walking up and down the tree, or
by selecting another branch for the tree. The views can be toggled between the
current file log and the tree vire.

The tree window will have the following layout:

       -------------------------------------------------------------------
      | commit:xxxxxxx          |                                         |
      | ... parent              |                                         |
      | ▾ dir_1                 |                                         |
      |  x file_1               |                                         |
      |  - file_2               |                                         |
      |  + file_3               |                                         |
      |   ▸ Another Dir         |                                         |
      |   file_3                |                                         |
      | ▸ dir_2                 |                                         |
      | ▸ dir_3 m               |                                         |
      | ▸ dir_4                 |                                         |
      | ▾ dir_5                 |                                         |
      |   ▾ dir_5_1             |                                         |
      |     ▾ dir_5_2           |                                         |
      | ▾ dir_6 x               |                                         |
      | ▸ dir_7 +               |                                         |
      |                         |                                         |
      .                         .                                         .
      .                         .                                         .
      .                         .                                         .
      |=========================|                                         |
      |  master   xxxxxxx some t|                                         |
      |  branch_1 xxxxxxx some t|                                         |
      |  branch_2 xxxxxxx some t|                                         |
      |  branch_3 xxxxxxx some t|                                         |
      |* branch_4 xxxxxxx some t|                                         |
      |  branch_5 xxxxxxx some t|                                         |
      |  branch_6 xxxxxxx some t|                                         |
       -------------------------------------------------------------------

5.1. Tree Usage

The tree can be navigated in the usual way, i.e. if a directory is closed
hitting <cr> while on it will open the sub-directory tree. If open this will
close it. If 'x' is pressed, then the parent node will be closed if the 

The tree recognises three different states for the files, local-only,
version-only and changed. The behaviour of the tree view differs with each of
these.

local-only: marked + (or without unicode + )
This file only exists in the local directory. The repo does not know about it
(or in only in the index). When <cr> is pressed on this file it will open the
local file.

version-only: marked x (or without unicode x )
This file only exists in the repository, there is no local file in the repository
that matches this file. pressing return will open the version extracted from
the current revision of the tree.

changed: marked - (or without unicode - )
This file exists in both the repository version and the local file system but
the two do not match. Selecting <cr> will open the version from the repository.
pressing 'l' will call the version from the local file system, and 'd' will
diff the two files.

Also, the directories may have trailing markers, for (sub)module directories
are marked with an 'm', directories that have been added '+' and the deleted
directories 'x'. Directories that are symbolic links are marked with and 'l'.

If the Directory has a loop in the symbolic link then it is marked with 'ł' (or
'B' without unicode).

Files that are the same will be unmarked and pressing <cr> will call the version
that is residing on the local file system.

5.2. Window Commands

Open Repository Version: <cr>

This opens the local version of the file.

Open Local Revision: 'l'

This key will cause the revision file to be opened. The version on disk will
be opened if it exists.

Open Repository Revision: 'p'

This key will cause the revision file to be opened, the version from the repository
will be opened. If it exists.

Diff Version: 'd'

This will diff the revision that is under the cursor.

Open History: 'h'

This will open the history window for this file.

Refresh Node: 'r'

This will refresh the node.

Refresh Tree: 'R'

This will refresh the whole tree.

Toggle Change Only: 'C'

This will only shjow changes between the current revision and the local tree.

Close Diff Buffer: <c-d>

Pressing these keys will cause the any diff windows that are open to close.

Reset Commit: <c-h>

This will reset the commit to HEAD. After some of the above commands the 
commit will change. 

Tree searches ']c', '[c', '[a', ']a':

These commands will search the tree and find changes. The 'c' versions of the
function will find files that have been amended. The 'a' variation will also
find the files that have been added or delete to the tree.

These searches start and end at the same level in the tree. Also the search
will continue from the last place in the tree that previous invocation ended.

With the |g:GITLOG_open_sub_on_search| flag set, it will open sub directories
and populate them. This can take a long time on big trees, be warned.

5.3 Selecting a Commit Tree

If you want to see the tree for any known commit. Goto the Log window select the
branch that the commit is on, then find the commit that you are interested in.
Goto the line it is on and press 't'. This will switch to the tree view at the
specific branch that is required.

5.4 Refreshing the tree

If files change on the file-system the tree can be refreshed by pressing the 'r'
key. This will cause the current directory under the cursor to be refreshed. It
will close any directories that have been opened. 

5.5. Going 'Change Only'

If you want to only see file changes in the tree, then press 'C' in the tree
window will toggle this mode. It will cause the tree to be re-walked with the
obvious overhead - but this only happens if the tree has not been walked at
least once before. Toggling is quite instantaneous after this happens.

==============================================================================
6. Mapping GitLog Functions                          *gitlog-mapping*

There is only one function that really required mapping and that is the
toggle function. As this is a single operation function I would assume that
you would attach it to a function key, so the following mapping would be useful
>
    :map <silent> <f7> :call GITLOG_FlipWindows()<cr>
    :map <silent> <c-f7> :call GITLOG_ToggleWindows()<cr>
<
This will install GITLOG on the <f7> key.

==============================================================================
7. File Commands									*gitlog-file-commands*

As git view is now a full tree system (and mostly as I have stopped using
NerdTree) it makes sense to be able to do some simple file system commands.

This is just to make is easier to use.

The commands that change the content of the files (ore create new ones) only
create/amend the files in the Vim buffer. It does no change the contents on
the file system by only in the editor. This gives the user the control to
save or not the changes.

The current list of commands are:

file create	'fc'	This will create a file on the file system.
file create	'fa'	This will add the current file to git.
file delete 'fd'	This will remove a file from the file system not the repo.
file remove 'fD'	This will remove a file from the system and repo.
file move   'fm'	This will move a file on the file system.
file move   'fM'	This will move a file on the file system and in the repo.
file revert 'fr'	This will revert the file to it's last committed state, if
                    in the history view, then it would revert to the current
					displayed commit.

File reverts are obviously a bit more complicated, so they follow the following
rules:
 If in tree-view it will do the following;
  1. If at HEAD and the file on the file-system has been changed from the repo version
     it will revert the file to the current HEAD version.
  2. If not at HEAD, it will revert the current file in the buffer to the
     version that is at the current commit.
  3. Do nothing.

 If in history view.
  1. It will load the selected commit into a buffer.

Note: reverts are hard reverts. They simply re-write the buffer with the file
from history. Reverts ae

==============================================================================
8. Configuring GitLog                               *gitlog-config*

There is only one function that really required mapping and that is the
toggle function. As this is a single operation function I would assume that
you would attach it to a function key, so the following mapping would be useful

g:GITLOG_walk_full_tree                             *g:GITLOG_walk_full_tree*
    When opening the tree window if this is set to '1' then the whole
    tree will be walked. It can take a long time to do the walk but
    takes the hit in one go. But more important to be able show only
    the differences will need for a full walk. [0]

g:GITLOG_directory_default                          *g:GITLOG_directory_default*
    When opening a full tree what should the default mode be for the directory
    that is opened. This mode only really effects the full tree mode as in the
    incremental mode having open children makes no sense. This does not have
    any effect in non-full mode. ['closed']

g:GITLOG_check_file_deferences                      *g:GITLOG_check_file_deferences*
    This makes the building of the tree faster. If set it means that the file
    contents are not checked. it does reduce the functionality if you are
    looking for merge checking and other things, but on big trees it can save
    a lot of time. This defaults to checking to be backwards compatible.[1]

g:GITLOG_show_only_changes                          *g:GITLOG_show_only_changes*
    This feature will cause only the files and directories that have changes
    that is files that have been added, deleted or amended (if file checking
    is on) and for directories that have a changed file (as just mentioned).
    This defaults to show all for backwards compatibility [0]

g:GITLOG_ignore_suffixes                            *g:GITLOG_ignore_suffixes*
    This switches on the pruning of the files. It will allow for a list of
    file suffixes that are going to be ignored when the tree is built. If
    the suffix list is changed then the tree will need to be fully rebuilt.
    The defaults are backward compatible.  []

g:GITLOG_ignore_directories                         *g:GITLOG_ignore_directories*
    This filters out specified directory names. That is all directories with
    these names will not be shown in the tree. As with the suffixes if the
    list is changed then the tree will need to be rebuilt. []

g:GITLOG_support_sub_git                            *g:GITLOG_support_sub_git*
    This allows for sub-git directories to be discovered. It will enumerate
    them. [1]

g:GITLOG_support_sub_repo                            *g:GITLOG_support_sub_repo*
    This turns on repo support. I have no idea why you would turn it off. But
    incase they are useen bugs.  [1]

g:GITLOG_show_hidden_files                            *g:GITLOG_show_hidden_files*
    This allows for hidden files to be turned off/on. The default is to not
    show hidden files. For the moment hidden files are '.' (dot) files. [0]

g:GITLOG_show_branch_window                           *g:GITLOG_show_branch_window*
    This will show the branch window. If you do not use it then switching
	the branch window off on startup gives you more space in big directory
	listings. The branch window can be toggled so this is not loss. [1]

g:GITLOG_open_sub_on_search                           *g:GITLOG_open_sub_on_search*
    When using the tree search functions this will allow the search
	to open and update any sub directories that it finds. This can
	make the search quite long as a lot of git accesses will be done.
	But this makes the search useful. [1]

==============================================================================
9. History                                       *gitlog-history*
  6.0.0: Jan 20, 2017
		 PA: BUG: Windows needs to pass unix paths to git
		 PA: BUG: Fix pathing for file diff
		 PA: BUG: Part of fix case-sensitive directory ordering.
		 PA: BUG: Fix setup for multi-byte encoding.
		 PA: BUG: Fix path handling for windows.

  5.1.1: Jan 1, 2017
         PA: BUG: When refreshing a dir propagate changes up the tree.
		 PA: BUG: Open files in directory that have been deleted.
         PA: BUG: Fixed undefined variable for old versions of git.
		 PA: BUG: Fixed work-dir work-tree incorrect parameter.
		 PA: BUG: fixed backwards compatibility issue with expand().
		 PA: BUG: fixed window error on exit.
		 PA: BUG: Fixed file-system deleted files not showing up in tree.
		 PA: BUG: Fixed tree reset in the root not correctly working.
		 PA: NEW_FEATURE: Added file commands.
		 PA: NEW_FEATURE: View commit as a patch.

  5.1.0: Dec 05, 2015
         PA: NEW_FEATURE: Toggle branch window.
         PA: NEW_FEATURE: Toggle Hidden files.
         PA: NEW_FEATURE: Jump to next change.
         PA: NEW_FEATURE: Add version to make life easier
         PA: NEW_FEATURE: Goto Previous Change
         PA: NEW_FEATURE: Goto Next Change
         PA: BUG: Not all hashes are 7 chars (and couple of syntax fixes)
         PA: BUG: correctly find sub-directories when not started at root
         PA: BUG: correctly find files when gitlog started in sub-dir
         PA: BUG: Redraw messed up git tree.
		 PA: BUG: tree open did not start at first tree item.

  5.0.0: May 16, 2015
         PA: BUG: Fixed not ignoring files, directories when doing a full walk.

  5.0.0: May 4, 2015
         PA: PERFORMANCE: Tree walking time substantially better.
         PA: PERFORMANCE: Reduced the amount of unrequired git accesses.
         PA: NEW_FEATURE: Properly coalescing of the repo and local directory names.
         PA: NEW_FEATURE: Make reset head also reset branch.
         PA: NEW_FEATURE: Goto latest on current selected branch.
         PA: NEW_FEATURE: sub-git trees supported.
         PA: NEW_FEATURE: Handling of Non-git trees better.
         PA: NEW_FEATURE: Repo support.
         PA: NEW_FEATURE: additional command.
         PA: BUG: If object type is different repo vs local add two items.
         PA: BUG: Added back local dot files (woops!).
         PA: BUG: Removed rubbish file added in empty directories.
         PA: BUG: Fixed toggle resetting branch state.
         PA: BUG: Syntax Fixes.

  4.0.2: Mar 20, 2015
         PA: BUG: Crashes when opened with a file open.

  4.0.1: Mar 17, 2015
         PA: BUG: Fixed issue with sym-link loops.
         PA: BUG: Fixed issue with trees not properly displaying in sub-dirs.
         PA: BUG: Fixed issue with documentation being wrong.
         PA: BUG: Fixed syntax highlighting.
         PA: BUG: Fixed manual opening of sub-dir was not correctly filtering.
         PA: NEW_FEATURE: Not walking links that loop.
         PA: NEW_FEATURE: Link highlighting.

  4.0.0: Mar 15, 2015
         PA: NEW FEATURE: Show only changed files.
         PA: NEW FEATURE: Filter files and directories by name.
         PA: NEW FEATURE: Walk Full Tree.
         PA: NEW FEATURE: Ability to not check files.
         PA: Fixed for git behaviour change observed with git 1.9.+
         PA: Reorganised the code base.

  3.1.1: June 27, 2013
         PA: Removed Scrolloff - did not know it was global and added as redraw to fix.
         PA: A couple of syntax fixes.

  3.1.0: Xxx nn, 2013
         PA: Changed <cr> on code tree to open local (also added 'p' for previous version).
         PA: Set scrolloff to 999 in tree - to center the tree.
         PA: Added indicator for the directories and their status.
         PA: Fixed syntax highlighting.
         PA: Added 'x' to close the parent in tree view.

  3.0.0: May 25, 2013
         PA: Added support for submodules.

  2.1.2: May 21, 2013
         PA: Fixed tree open.
         PA: Fixed being able to open in any default mode.
         PA: Made open tree view a bit better.

  2.1.1: May 03, 2013
         PA: Fixed silly start-up issue.

  2.1.0: March 29, 2013
         PA: Fixed empty directory issue.
         PA: Added 'refresh' functions for tree.

  2.0.2: March 26, 2013
         PA: Released wrong version and broke toggle and syntax.

  2.0.0: March 26, 2013
         PA: Added the Repository History Tree.
         PA: Also fixed minor issue with the branch selection being wrong.

  1.3.1: March 8, 2013
         PA: Fixed problem with marge branches not being diff'ed and fixed syntax
             highlighting to handle the branches.

  1.3.0: January 8, 2013
         PA: Re-wrote the way that the files were read so it works in console mode.

  1.2.0: December 14, 2012
         PA: Added repository search capability.
         PA: Added syntax highlighting.
         PA: Fixed the way that buffers are created to stop leaking buffers.
         PA: Fixed the way it closes buffers to stop it closing the editor.

  1.1.2: December 12, 2012
         PA: Fixed broken plugin. Order of parameter setting caused by the last fix,
             broke the plugin. Also fixed problem with un-escaped branchname causing
             git to not return list of changes.

  1.1.1: November 21, 2012
         PA: Fixed issue with not finding history if the editor was not launched
             in the repository tree.

  1.1.0: October 27, 2012:
         PA: Added functionality to the branch window. Now selecting the branch

  1.1.0: October 27, 2012:
         PA: Added functionality to the branch window. Now selecting the branch
             will update the log window to reflect the commits in that branch.

         PA: Added the help file.

  1.0.0: <some time in the past>
         PA: Initial release.

vim: ts=4 ft=help tw=78
