dotfiles.git

1) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/dblume/gittab/main/LICENSE)
2) ![vim8](https://img.shields.io/badge/vim-8.x-green.svg)
3) 
4) ## Vim Git-Tab
5) 
6) These are handy context-sensitive Git commands in Vim that load the results in

7) a new tab. The commands infer what you want from the current filename and
8) whether there's a commit hash under the cursor.

9) 

10) These commands are for investigating the history of files. They are:

11) 
12) * `Blame`
13) * `Log`
14) * `Show` and `ShowFile`
15) * `Diff`
16) 

17) This simple plugin is enough to do 95% of the Git dives I do. If you still want
18) to do even more with Git while in Vim, consider Tim Pope's comprehensive
19) [vim-fugitive](https://github.com/tpope/vim-fugitive).

20) 
21) ## Installation
22) 
23) Install into Vim's built-in package support:
24) 
25)     mkdir -p ~/.vim/pack/plugins/start
26)     cd ~/.vim/pack/plugins/start
27)     git clone --filter=blob:none -b main --single-branch https://github.com/dblume/gittab
28)     vim -u NONE -c "helptags gittab/doc" -c q
29) 

30) 
31) ## Common Use Example
32) 
33) Say you're on "index.html", and you need to know why a section looks the way

34) it does. Run `:Blame` to see a buffer of "git blame" open at the same line
35) where you are so you don't lose any context.
36) 
37) Or run `:Log` to see a list of only the commits that _affect that file_. This
38) is nice in a repo of thousands of commits, but only dozens are to this file.

39) 
40) If you see a commit of interest, move the cursor over it, and type  `:Diff` to
41) see what changes were made by that commit, or `:Show` to see the full commit
42) description.
43) 
44) Then you can keep exploring, and each command infers what you want by which
45) type of buffer you're in or what commit your cursor is on.
46) 
47) 

48) ## The Commands
49) 
50) When you're browsing a file in a Git repository, these commands provide a very
51) simple and convenient flow for digging into their history.
52) 
53) All you have to know is Blame, Log, Show, and Diff.
54) 

55) The following image is an oversimplification, but shows that with the above
56) four commands, one can easily and quickly navigate various views of a file and
57) its commit history.
58) 
59) ![gittab.png](https://dblume.github.io/images/gittab.png)
60) 
61) ### :Blame

62) 
63) When you're on a regular file or a `:ShowFile` buffer, opens up a `git blame` 

64) buffer in a new tab and positions the cursor at the same relative spot in the
65) Blame buffer.

66) 
67) Example, run Blame on a `:ShowFile` buffer named "git show 1234abcd:README.md",
68) and you get a `:Blame` buffer named "git blame 1234abcd -- README.md".
69) 

70) ### :Log

71) 
72) When you're on a regular file or a `:ShowFile` buffer, opens up a `git log`

73) buffer in a new tab for the commits that _affect only that file_. By default,
74) runs log as:

75) 
76)     git log --no-color --graph --date=short --pretty="format:%h %ad %s %an %d"
77) 
78) And you can pass in additional Git arguments like `--all`.
79) 
80)     :Log --all
81) 
82) The reason Log defaults to one-line logs is because `:Show` and `:Diff` are so
83) easy to use to dive in deeper to the individual commits.
84) 
85) Handy arguments are `--all`, `--merges`, `--date-order`, `--first-parent`, and
86) `--ancestry-path`.
87) 

88) ### :Show and :ShowFile

89) 
90) These require the cursor to be positioned on a hash, so you'd most likely be
91) in a `:Log` or `:Blame` buffer when you want to use these commands.
92) 

93) When you're on a `:Log` or `:Blame` buffer  **`:Show`** opens a buffer in a
94) new tab that shows the full commit message for the hash under the cursor.

95) 
96) **`:ShowFile`** opens a buffer in a new tab that shows the contents of the file
97) at the hash under the cursor.
98) 
99) Ex., If the cursor is on "1234abcd" on `:Blame` buffer `git blame -- README.md`
100) then:
101) 
102) | Command   | Resultant Buffer |
103) | ---       | ---              |
104) | :Show     | git show 1234abcd -- README.md |
105) | :ShowFile | git show 1234abcd:README.md |
106) 

107) ### :Diff

108) 
109) If you're on a regular file that's different from HEAD, `:Diff` will perform a
110) `git diff` on the file from HEAD. If it's the same as HEAD, then `:Diff` will
111) perform a `git diff` against that file's previous commit.
112) 
113) If the cursor is on a commit hash (as available on :Blame, :Log, and :Show 
114) buffers), then `:Diff` will perform a diff against the previous commit to that
115) one.
116) 

117) If the active window is of a `:Diff` buffer, then `:Diff` will perform a
118) `git diff` of that buffer with that revision's parent.
119) 

120) ## Is it any good?
121) 
122) [Yes](https://news.ycombinator.com/item?id=3067434).
123) 

124) The diagram was made with [Excalidraw](https://excalidraw.com/).
125)