Skip to content

Commit 1951e39

Browse files
mceplmcepl
committed
doc: add manpage
And a snippet to Makefile to generate HTML and manpage.
1 parent ebb8815 commit 1951e39

File tree

3 files changed

+266
-1
lines changed

3 files changed

+266
-1
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
git-fixup.1
2+
git-fixup.html

‎Makefile‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
PREFIX?=/usr/local
22
INSTALLDIR?=$(PREFIX)
3+
MANDIR?=$(INSTALLDIR)/usr/share/man/man1
34
INSTALL=install
45

5-
install:
6+
all: git-fixup.1 git-fixup.html
7+
8+
install: git-fixup.1 install-fish install-zsh
69
${INSTALL} -d ${DESTDIR}${INSTALLDIR}/bin
710
${INSTALL} -m755 git-fixup ${DESTDIR}${INSTALLDIR}/bin/git-fixup
11+
${INSTALL} -m644 git-fixup.1 ${DESTDIR}${MANDIR}/man1/git-fixup.1
812

913
install-fish:
1014
${INSTALL} -d ${DESTDIR}${INSTALLDIR}/share/fish/vendor_completions.d/
@@ -13,3 +17,14 @@ install-fish:
1317
install-zsh:
1418
${INSTALL} -d ${DESTDIR}${INSTALLDIR}/share/zsh/site-functions
1519
${INSTALL} -m644 completion.zsh ${DESTDIR}${INSTALLDIR}/share/zsh/site-functions/_git-fixup
20+
21+
git-fixup.1: git-fixup.txt
22+
asciidoctor -b manpage -d manpage -o $@ $<
23+
24+
git-fixup.html: git-fixup.txt
25+
asciidoctor -d manpage -o $@ $<
26+
27+
clean:
28+
rm -f git-fixup.html git-fixup.1 *~
29+
30+
.PHONY: install-fish install-zsh

‎git-fixup.txt‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
git-fixup(1)
2+
============
3+
4+
NAME
5+
----
6+
git-fixup - Fighting the copy-paste element of your rebase workflow
7+
8+
SYNOPSIS
9+
--------
10+
[verse]
11+
'git-fixup' [-s|--squash] [-f|--fixup] [-a|--amend] [-c|--commit] [--no-verify]
12+
[--rebase] [-b|--base <rev>] [<ref>]
13+
14+
15+
DESCRIPTION
16+
-----------
17+
Fighting the copy-paste element of your rebase workflow.
18+
19+
`git fixup <ref>` is simply an alias for `git commit --fixup <ref>`. That's
20+
just a convenience feature that can be also be used to trigger tab completion.
21+
22+
The magic is in plain `git fixup` without any arguments. It finds which
23+
lines/files you have changed, uses git blame/log to find the most recent commits
24+
that touched those lines/files, and displays a list for you to pick from. This
25+
is a convenient alternative to manually searching through the commit log and
26+
copy-pasting the commit hash.
27+
28+
For this tool to make any sense you should enable the `rebase.autosquash`
29+
setting in the git config, or use the `--rebase` option.
30+
31+
OPTIONS
32+
-------
33+
34+
-s::
35+
--squash::
36+
Instruct `git-fixup` to create a `squash!` commit instead of a `fixup!` commit.
37+
38+
Squashing gives you the opportunity to edit the commit message before
39+
the commits are squashed together.
40+
41+
Default action can be configured by setting <<fixupaction,fixup.action>>
42+
43+
-f::
44+
--fixup::
45+
Instruct `git-fixup` to create `fixup!` commit (This is the default).
46+
47+
Default action can be configured by setting <<fixupaction,fixup.action>>
48+
49+
-a::
50+
--amend::
51+
Instruct `git-fixup` to create an `amend!` commit.
52+
53+
Default action can be configured by setting <<fixupaction,fixup.action>>
54+
55+
-c::
56+
--commit::
57+
Instead of listing the suggested commits show a menu to pick a commit to
58+
create a fixup/squash commit of.
59+
60+
A <<the-default-menu,default menu>> is provided that is intentionally very
61+
simple and with no advanced features. Instead of using it you can tell `git
62+
fixup` to use an external tool for the menu by defining a command line via
63+
either the <<fixupmenu,fixup.menu>> setting in the git config or the `GITFIXUPMENU`
64+
environment variable (the latter overrides the former).
65+
66+
```bash
67+
# Use fzf as a menu program
68+
$ GITFIXUPMENU=fzf git fixup -c
69+
```
70+
71+
This option can be enabled by default by setting <<fixupcommit,fixup.commit>>
72+
in the git config.
73+
74+
--no-commit::
75+
Don't show the commit menu even if previously instructed to do so.
76+
77+
--rebase::
78+
Call an interactive rebase right after the commit is created, to automatically apply the
79+
fix-up into the target commit. This is merely to avoid doing two commands one after the
80+
other (`git fixup && git rebase`).
81+
82+
This simply calls `git rebase --interactive --autosquash target~1`, with the target being the
83+
commit to fix-up.
84+
85+
Default rebase/no-rebase can be configured by setting <<fixuprebase,fixup.rebase>>
86+
87+
--no-rebase::
88+
Don't do a rebase even if previously instructed to do so (useful to bypass <<fixuprebase,fixup.rebase>>)
89+
90+
--no-verify::
91+
Bypass the pre-commit and commit-msg hooks. (see `git help commit`)
92+
93+
94+
--base <rev>::
95+
This option receives as argument the revision to be used as base commit for
96+
the search of fixup/squash candidates. You can use anything that resolves to a
97+
commit. The special value `closest` resolves to the closest ancestor branch of
98+
the current head.
99+
100+
If omitted, the default base commit is resolved in the following order:
101+
102+
1. The value of the environment variable `GITFIXUPBASE` if present;
103+
2. The value of the configuration key `fixup.base` if present;
104+
3. The branch configured as upstream of the current one (i.e. `@{upstream}`)
105+
if existing;
106+
4. Finally, the root commit (i.e. full history) if nothing of the above is
107+
satisfied.
108+
109+
110+
Configuration
111+
-------------
112+
113+
`git-fixup` uses configuration from the ENVIRONMENT or from `git config`
114+
115+
fixup.base
116+
~~~~~~~~~~
117+
118+
Or `GITFIXUPBASE`
119+
120+
The default argument for `--base`. You can set the value `closest` to make
121+
`git-fixup` use the closest ancestor branch by default, for example.
122+
123+
fixup.action
124+
~~~~~~~~~~~~
125+
[[fixupaction]]
126+
127+
Or `GITFIXUPACTION`
128+
129+
Decides if the default actions will be `fixup` or `squash`.
130+
131+
fixup.commit
132+
~~~~~~~~~~~~
133+
[[fixupcommit]]
134+
135+
Or `GITFIXUPCOMMIT`
136+
137+
Decides if the commit menu should be displayed instead of the commit list by
138+
default.
139+
140+
```bash
141+
# Enable --commit for all my projects
142+
$ git config --global fixup.commit true
143+
```
144+
145+
fixup.rebase
146+
~~~~~~~~~~~~
147+
[[fixuprebase]]
148+
149+
Or `GITFIXUPREBASE`
150+
151+
Decides if `git rebase` should be called right after the `git commit` call.
152+
153+
```bash
154+
# Enable --rebase for all my projects
155+
$ git config --global fixup.rebase true
156+
```
157+
158+
fixup.menu
159+
~~~~~~~~~~
160+
[[fixupmenu]]
161+
162+
Or `GITFIXUPMENU`
163+
164+
Sets the command that will be used to display the commit menu. If not set
165+
a simple [default menu](the-default-menu) will be used.
166+
167+
See <<external-menu,External menu>> for more details and a more advanced
168+
example.
169+
170+
Tab completion
171+
--------------
172+
173+
Tab completion for zsh/fish is implemented. The suggestions for the tab completion
174+
are the suggested fixup bases as generated by running the tool without any
175+
arguments.
176+
177+
To be able to tab complete the command itself add a line like this to your zsh
178+
configuration::
179+
180+
zstyle ':completion:*:*:git:*' user-commands fixup:'Create a fixup commit'
181+
182+
183+
External menu
184+
-------------
185+
[[external-menu]]
186+
187+
In order to use an external tool for display the commit menu, you need to
188+
either define the <<fixupmenu,fixup.menu>> setting in the git config or set the
189+
`GITFIXUPMENU` environment variable with the command for the menu. The menu
190+
command must receive as input the lines as the options for the user and return
191+
the selected line to the standard output.
192+
193+
The following example is a fragment of a git config that makes `git fixup
194+
--commit` display a nice menu with https://github.com/junegunn/fzf[fzf]:
195+
196+
```ini
197+
[fixup]
198+
menu = fzf --height '60%' \
199+
--bind 'tab:toggle-preview' \
200+
--preview 'git show --color {+1}' \
201+
--preview-window=up:80% \
202+
--prompt 'Select commit: '
203+
```
204+
205+
The default menu
206+
----------------
207+
[[the-default-menu]]
208+
209+
If you have not configured an external menu, the default menu is used. See the
210+
example below:
211+
212+
```bash
213+
$ git fixup -c
214+
1) 500be603c66040dd8a9ca18832d6221c00e96184 [F] Add README.md <[email protected]>
215+
2) ddab3b03da529af5303531a3d4127e3663063e08 [F] Add index.js <[email protected]>
216+
Which commit should I fixup? <your-selection>
217+
```
218+
219+
Here `<your-selection>` should be the number of the desired commit in the list.
220+
You can use `q` to abort the operation and `h` to see a help message for the
221+
menu.
222+
223+
If the commit title alone is not enough for you to decide, you can use `show
224+
<number>` to call `git show` on the `<number>`-th commit of the menu.
225+
226+
Changelog
227+
---------
228+
229+
See link:CHANGELOG.md[CHANGELOG.md]
230+
231+
Authors
232+
-------
233+
234+
The fine people who have contributed to this script in ASCIIbetical order.
235+
236+
- Cristiano Giuffrida (https://github.com/cgiuffr[cgiuffr])
237+
- David Keijser (https://github.com/keis[keis])
238+
- Elan Ruusamäe (https://github.com/glensc[glensc])
239+
- Federico del Mazo (https://github.com/FdelMazo[FdelMazo])
240+
- Gustavo Sousa (https://github.com/guludo[guludo])
241+
- Joe Shaw (https://github.com/joeshaw[joeshaw])
242+
- Philippe (https://github.com/pe[pe])
243+
- Rickard Dybeck (https://github.com/alde[alde])
244+
- Tiago Ribeiro (https://github.com/fixe[fixe])
245+
246+
GIT
247+
---
248+
Part of the linkgit:git[1] suite

0 commit comments

Comments
 (0)