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 list of the commits that _affect only that file_.
35) The Blame buffer opens at the same position you were at so you don't lose any
36) context.
37) 
38) If you see a commit of interest, move the cursor over it, and type  `:Diff` to
39) see what changes were made by that commit, or `:Show` to see the full commit
40) description.
41) 
42) Then you can keep exploring, and each command infers what you want by which
43) type of buffer you're in or what commit your cursor is on.
44) 
45) 

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

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

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

62) buffer in a new tab that _affect only the file at that commit_, and positions
63) the cursor at the same relative spot in the Blame buffer.

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

68) ### :Log

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

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

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

86) ### :Show and :ShowFile

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

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

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

105) ### :Diff

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

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

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

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