Tweaks to gittab/README.md (54ff580) - dotfiles.git

.vim/pack/plugins/start/gittab/README.md

@@ -4,18 +4,19 @@
 ## Vim Git-Tab
 
 These are handy context-sensitive Git commands in Vim that load the results in
-a new tab. The commands automatically infer what you want from the current
-filename and whether there's a commit hash under the cursor.
+a new tab. The commands infer what you want from the current filename and
+whether there's a commit hash under the cursor.
 
-These commands are for investigating the history of files. The supported
-commands are:
+These commands are for investigating the history of files. They are:
 
 * `Blame`
 * `Log`
 * `Show` and `ShowFile`
 * `Diff`
 
-If you want to do more with Git while in Vim, consider Tim Pope's [vim-fugitive](https://github.com/tpope/vim-fugitive).
+This simple plugin is enough to do 95% of the Git dives I do. If you still want
+to do even more with Git while in Vim, consider Tim Pope's comprehensive
+[vim-fugitive](https://github.com/tpope/vim-fugitive).
 
 ## Installation
 
@@ -26,6 +27,22 @@ Install into Vim's built-in package support:
     git clone --filter=blob:none -b main --single-branch https://github.com/dblume/gittab
     vim -u NONE -c "helptags gittab/doc" -c q
 
+
+## Common Use Example
+
+Say you're on "index.html", and you need to know why a section looks the way
+it does. Run `:Blame` to see a list of the commits that _affect only that file_.
+The Blame buffer opens at the same position you were at so you don't lose any
+context.
+
+If you see a commit of interest, move the cursor over it, and type  `:Diff` to
+see what changes were made by that commit, or `:Show` to see the full commit
+description.
+
+Then you can keep exploring, and each command infers what you want by which
+type of buffer you're in or what commit your cursor is on.
+
+
 ## The Commands
 
 When you're browsing a file in a Git repository, these commands provide a very
@@ -33,19 +50,26 @@ simple and convenient flow for digging into their history.
 
 All you have to know is Blame, Log, Show, and Diff.
 
-#### :Blame
+The following image is an oversimplification, but shows that with the above
+four commands, one can easily and quickly navigate various views of a file and
+its commit history.
+
+![gittab.png](https://dblume.github.io/images/gittab.png)
+
+### :Blame
 
 When you're on a regular file or a `:ShowFile` buffer, opens up a `git blame` 
-buffer in a new tab for the file at that commit, and positions the
-cursor at the same relative spot.
+buffer in a new tab that _affect only the file at that commit_, and positions
+the cursor at the same relative spot in the Blame buffer.
 
 Example, run Blame on a `:ShowFile` buffer named "git show 1234abcd:README.md",
 and you get a `:Blame` buffer named "git blame 1234abcd -- README.md".
 
-#### :Log
+### :Log
 
 When you're on a regular file or a `:ShowFile` buffer, opens up a `git log`
-buffer in a new tab. By default, runs log as:
+buffer in a new tab for the commits that _affect only that file_. By default,
+runs log as:
 
     git log --no-color --graph --date=short --pretty="format:%h %ad %s %an %d"
 
@@ -59,14 +83,13 @@ easy to use to dive in deeper to the individual commits.
 Handy arguments are `--all`, `--merges`, `--date-order`, `--first-parent`, and
 `--ancestry-path`.
 
-#### :Show and :ShowFile
+### :Show and :ShowFile
 
 These require the cursor to be positioned on a hash, so you'd most likely be
 in a `:Log` or `:Blame` buffer when you want to use these commands.
 
-When you're on a `:Blame` buffer, a `:Log` buffer, **`:Show`** opens a
-buffer in a new tab that shows the full commit message for the hash under the
-cursor.
+When you're on a `:Log` or `:Blame` buffer  **`:Show`** opens a buffer in a
+new tab that shows the full commit message for the hash under the cursor.
 
 **`:ShowFile`** opens a buffer in a new tab that shows the contents of the file
 at the hash under the cursor.
@@ -79,7 +102,7 @@ then:
 | :Show     | git show 1234abcd -- README.md |
 | :ShowFile | git show 1234abcd:README.md |
 
-#### :Diff
+### :Diff
 
 If you're on a regular file that's different from HEAD, `:Diff` will perform a
 `git diff` on the file from HEAD. If it's the same as HEAD, then `:Diff` will
@@ -89,10 +112,15 @@ If the cursor is on a commit hash (as available on :Blame, :Log, and :Show
 buffers), then `:Diff` will perform a diff against the previous commit to that
 one.
 
+If the active window is of a `:Diff` buffer, then `:Diff` will perform a
+`git diff` of that buffer with that revision's parent.
+
 ## Is it any good?
 
 [Yes](https://news.ycombinator.com/item?id=3067434).
 
+The diagram was made with [Excalidraw](https://excalidraw.com/).
+
 ## Licence
 
 This software uses the [MIT License](https://raw.githubusercontent.com/dblume/gittab/main/LICENSE.txt)


...	...	@@ -4,18 +4,19 @@
4	4	## Vim Git-Tab
5	5
6	6	These are handy context-sensitive Git commands in Vim that load the results in
7		-a new tab. The commands automatically infer what you want from the current
8		-filename and whether there's a commit hash under the cursor.
	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	9
10		-These commands are for investigating the history of files. The supported
11		-commands are:
	10	+These commands are for investigating the history of files. They are:
12	11
13	12	* `Blame`
14	13	* `Log`
15	14	* `Show` and `ShowFile`
16	15	* `Diff`
17	16
18		-If you want to do more with Git while in Vim, consider Tim Pope's [vim-fugitive](https://github.com/tpope/vim-fugitive).
	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).
19	20
20	21	## Installation
21	22
...	...	@@ -26,6 +27,22 @@ Install into Vim's built-in package support:
26	27	git clone --filter=blob:none -b main --single-branch https://github.com/dblume/gittab
27	28	vim -u NONE -c "helptags gittab/doc" -c q
28	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	+
29	46	## The Commands
30	47
31	48	When you're browsing a file in a Git repository, these commands provide a very
...	...	@@ -33,19 +50,26 @@ simple and convenient flow for digging into their history.
33	50
34	51	All you have to know is Blame, Log, Show, and Diff.
35	52
36		-#### :Blame
	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
37	60
38	61	When you're on a regular file or a `:ShowFile` buffer, opens up a `git blame`
39		-buffer in a new tab for the file at that commit, and positions the
40		-cursor at the same relative spot.
	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.
41	64
42	65	Example, run Blame on a `:ShowFile` buffer named "git show 1234abcd:README.md",
43	66	and you get a `:Blame` buffer named "git blame 1234abcd -- README.md".
44	67
45		-#### :Log
	68	+### :Log
46	69
47	70	When you're on a regular file or a `:ShowFile` buffer, opens up a `git log`
48		-buffer in a new tab. By default, runs log as:
	71	+buffer in a new tab for the commits that _affect only that file_. By default,
	72	+runs log as:
49	73
50	74	git log --no-color --graph --date=short --pretty="format:%h %ad %s %an %d"
51	75
...	...	@@ -59,14 +83,13 @@ easy to use to dive in deeper to the individual commits.
59	83	Handy arguments are `--all`, `--merges`, `--date-order`, `--first-parent`, and
60	84	`--ancestry-path`.
61	85
62		-#### :Show and :ShowFile
	86	+### :Show and :ShowFile
63	87
64	88	These require the cursor to be positioned on a hash, so you'd most likely be
65	89	in a `:Log` or `:Blame` buffer when you want to use these commands.
66	90
67		-When you're on a `:Blame` buffer, a `:Log` buffer, `:Show` opens a
68		-buffer in a new tab that shows the full commit message for the hash under the
69		-cursor.
	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.
70	93
71	94	`:ShowFile` opens a buffer in a new tab that shows the contents of the file
72	95	at the hash under the cursor.
...	...	@@ -79,7 +102,7 @@ then:
79	102	\| :Show \| git show 1234abcd -- README.md \|
80	103	\| :ShowFile \| git show 1234abcd:README.md \|
81	104
82		-#### :Diff
	105	+### :Diff
83	106
84	107	If you're on a regular file that's different from HEAD, `:Diff` will perform a
85	108	`git diff` on the file from HEAD. If it's the same as HEAD, then `:Diff` will
...	...	@@ -89,10 +112,15 @@ If the cursor is on a commit hash (as available on :Blame, :Log, and :Show
89	112	buffers), then `:Diff` will perform a diff against the previous commit to that
90	113	one.
91	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	+
92	118	## Is it any good?
93	119
94	120	[Yes](https://news.ycombinator.com/item?id=3067434).
95	121
	122	+The diagram was made with [Excalidraw](https://excalidraw.com/).
	123	+
96	124	## Licence
97	125
98	126	This software uses the [MIT License](https://raw.githubusercontent.com/dblume/gittab/main/LICENSE.txt)
99	127