1 .\"
2 .\" Copyright (c) 2018 Stefan Sperling
3 .\"
4 .\" Permission to use, copy, modify, and distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
7 .\"
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\"
16 .Dd $Mdocdate$
17 .Dt TOG 1
18 .Os
19 .Sh NAME
20 .Nm tog
21 .Nd Git repository browser
22 .Sh SYNOPSIS
23 .Nm
24 .Ar command
25 .Op Fl h
26 .Op Ar arg ...
27 .Sh DESCRIPTION
28 .Nm
29 is an interactive read-only browser for Git repositories.
30 This repository format is described in
31 .Xr git-repository 5 .
32 .Pp
33 .Nm
34 supports several types of views which display repository data:
35 .Bl -tag -width Ds
36 .It Log view
37 Displays commits in the repository's history.
38 This view is displayed initially if no
39 .Ar command
40 is specified.
41 .It Diff view
42 Displays changes made in a particular commit.
43 .It Blame view
44 Displays the line-by-line history of a file.
45 .It Tree view
46 Displays the tree corresponding to a particular commit.
47 .El
48 .Pp
49 .Nm
50 provides global and command-specific key bindings and options.
51 The global key bindings are:
52 .Bl -tag -width Ds
53 .It Cm Q
54 Quit
55 .Nm .
56 .It Cm q
57 Quit the view which is in focus.
58 .It Cm Tab
59 Switch focus between views.
60 .It Cm f
61 Toggle fullscreen mode for a split-screen view.
62 .Nm
63 will automatically use split-screen views if the size of the terminal
64 window is sufficiently large.
65 .El
66 .Pp
67 Global options must precede the command name, and are as follows:
68 .Bl -tag -width tenletters
69 .It Fl h
70 Display usage information.
71 .It Fl V
72 Display program version and exit immediately.
73 .El
74 .Pp
75 The commands for
76 .Nm
77 are as follows:
78 .Bl -tag -width blame
79 .It Cm log Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
80 Display history of a repository.
81 If a
82 .Ar path
83 is specified, show only commits which modified this path.
84 .Pp
85 This command is also executed if no explicit command is specified.
86 .Pp
87 The key bindings for
88 .Cm tog log
89 are as follows:
90 .Bl -tag -width Ds
91 .It Cm Down-arrow, j, >, Full stop
92 Move the selection cursor down.
93 .It Cm Up-arrow, k, <, Comma
94 Move the selection cursor up.
95 .It Cm Page-down, Ctrl+f
96 Move the selection cursor down one page.
97 .It Cm Page-up, Ctrl+b
98 Move the selection cursor up one page.
99 .It Cm Enter, Space
100 Open a
101 .Cm diff
102 view showing file changes made in the currently selected commit.
103 .It Cm t
104 Open a
105 .Cm tree
106 view showing the tree for the currently selected commit.
107 .It Cm Backspace
108 Show log entries for the parent directory of the currently selected path,
109 unless an active search is in progress in which case
110 .Cm Backspace
111 aborts the search.
112 .It Cm /
113 Prompt for a search pattern and start searching for matching commits.
114 The search pattern is an extended regular expression which is matched
115 against a commit's author name, committer name, log message, and
116 commit ID SHA1 hash.
117 Regular expression syntax is documented in
118 .Xr re_format 7 .
119 .It Cm n
120 Find the next commit which matches the current search pattern.
121 Searching continues until either a match is found or the
122 .Cm Backspace
123 key is pressed.
124 .It Cm N
125 Find the previous commit which matches the current search pattern.
126 Searching continues until either a match is found or the
127 .Cm Backspace
128 key is pressed.
129 .It Cm Ctrl+l
130 Reload the log view with new commits found in the repository.
131 .El
132 .Pp
133 The options for
134 .Cm tog log
135 are as follows:
136 .Bl -tag -width Ds
137 .It Fl c Ar commit
138 Start traversing history at the specified
139 .Ar commit .
140 The expected argument is the name of a branch or a commit ID SHA1 hash.
141 An abbreviated hash argument will be expanded to a full SHA1 hash
142 automatically, provided the abbreviation is unique.
143 If this option is not specified, default to the work tree's current branch
144 if invoked in a work tree, or to the repository's HEAD reference.
145 .It Fl r Ar repository-path
146 Use the repository at the specified path.
147 If not specified, assume the repository is located at or above the current
148 working directory.
149 .El
150 .It Cm diff Oo Ar repository-path Oc Ar object1 object2
151 Display the differences between two objects in the repository.
152 Each
153 .Ar object
154 argument is an object ID SHA1 hash.
155 An abbreviated hash argument will be expanded to a full SHA1 hash
156 automatically, provided the abbreviation is unique.
157 Both objects must be of the same type (blobs, trees, or commits).
158 If the
159 .Ar repository path
160 is omitted, use the current working directory.
161 .Pp
162 The key bindings for
163 .Cm tog diff
164 are as follows:
165 .Bl -tag -width Ds
166 .It Cm Down-arrow, j
167 Scroll down.
168 .It Cm Up-arrow, k
169 Scroll up.
170 .It Cm Page-down, Space, Ctrl+f
171 Scroll down one page.
172 .It Cm Page-up, Ctrl+b
173 Scroll up one page.
174 .It Cm \&[
175 Reduce the amount of diff context lines.
176 .It Cm \&]
177 Increase the amount of diff context lines.
178 .It Cm <, Comma
179 If the diff view was opened via the log view, move to the previous (younger)
180 commit.
181 .It Cm >, Full stop
182 If the diff view was opened via the log view, move to the next (older) commit.
183 .El
184 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
185 Display line-by-line history of a file at the specified path.
186 .Pp
187 The key bindings for
188 .Cm tog blame
189 are as follows:
190 .Bl -tag -width Ds
191 .It Cm Down-arrow, j, Page-down, Space
192 Move the selection cursor down.
193 .It Cm Up-arrow, k, Page-up
194 Move the selection cursor up.
195 .It Cm Enter
196 Open a
197 .Cm diff
198 view for the currently selected line's commit.
199 .It Cm b
200 Reload the
201 .Cm blame
202 view with the version of the file as found in the currently
203 selected line's commit.
204 .It Cm p
205 Reload the
206 .Cm blame
207 view with the version of the file as found in the parent commit of the
208 currently selected line's commit.
209 .It Cm B
210 Reload the
211 .Cm blame
212 view with the previously blamed commit.
213 .It Cm /
214 Prompt for a search pattern and start searching for matching line.
215 The search pattern is an extended regular expression.
216 Regular expression syntax is documented in
217 .Xr re_format 7 .
218 .It Cm n
219 Find the next line which matches the current search pattern.
220 .It Cm N
221 Find the previous line which matches the current search pattern.
222 .El
223 .Pp
224 The options for
225 .Cm tog blame
226 are as follows:
227 .Bl -tag -width Ds
228 .It Fl c Ar commit
229 Start traversing history at the specified
230 .Ar commit .
231 The expected argument is the name of a branch or a commit ID SHA1 hash.
232 An abbreviated hash argument will be expanded to a full SHA1 hash
233 automatically, provided the abbreviation is unique.
234 .It Fl r Ar repository-path
235 Use the repository at the specified path.
236 If not specified, assume the repository is located at or above the current
237 working directory.
238 .El
239 .It Cm tree Oo Fl c Ar commit Oc Op Ar repository-path
240 Display the repository tree.
241 If the
242 .Ar repository path
243 is omitted, assume the repository is located in the current working directory.
244 .Pp
245 Displayed tree entries may carry one of the following trailing annotations:
246 .Bl -column YXZ description
247 .It @ Ta entry is a symbolic link
248 .It / Ta entry is a directory
249 .It * Ta entry is an executable file
250 .It $ Ta entry is a Git submodule
251 .El
252 .Pp
253 The key bindings for
254 .Cm tog tree
255 are as follows:
256 .Bl -tag -width Ds
257 .It Cm Down-arrow, j, Page-down
258 Move the selection cursor down.
259 .It Cm Up-arrow, k, Page-up
260 Move the selection cursor up.
261 .It Cm Enter
262 Enter the currently selected directory, or switch to the
263 .Cm blame
264 view for the currently selected file.
265 .It Cm l
266 Open a
267 .Cm log
268 view for the currently selected tree entry.
269 .It Cm Backspace
270 Move back to the parent directory.
271 .It Cm i
272 Show object IDs for all objects displayed in the
273 .Cm tree
274 view.
275 .It Cm /
276 Prompt for a search pattern and start searching for matching tree entries.
277 The search pattern is an extended regular expression which is matched
278 against the tree entry's name.
279 Regular expression syntax is documented in
280 .Xr re_format 7 .
281 .It Cm n
282 Find the next tree entry which matches the current search pattern.
283 .It Cm N
284 Find the previous tree entry which matches the current search pattern.
285 .El
286 .Pp
287 The options for
288 .Cm tog tree
289 are as follows:
290 .Bl -tag -width Ds
291 .It Fl c Ar commit
292 Start traversing history at the specified
293 .Ar commit .
294 The expected argument is the name of a branch or a commit ID SHA1 hash.
295 An abbreviated hash argument will be expanded to a full SHA1 hash
296 automatically, provided the abbreviation is unique.
297 .El
298 .El
299 .Sh EXIT STATUS
300 .Ex -std tog
301 .Sh SEE ALSO
302 .Xr got 1 ,
303 .Xr git-repository 5 ,
304 .Xr re_format 7
305 .Sh AUTHORS
306 .An Stefan Sperling Aq Mt stsp@openbsd.org
307 .An Joshua Stein Aq Mt jcs@openbsd.org