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 .Op Ar command
25 .Op Fl h
26 .Op Ar arg ...
27 .Pp
28 .Nm
29 .Ar path
30 .Sh DESCRIPTION
31 .Nm
32 is an interactive read-only browser for Git repositories.
33 This repository format is described in
34 .Xr git-repository 5 .
35 .Pp
36 .Nm
37 supports several types of views which display repository data:
38 .Bl -tag -width Ds
39 .It Log view
40 Displays commits in the repository's history.
41 This view is displayed initially if no
42 .Ar command
43 is specified, or if just a
44 .Ar path
45 is specified.
46 .It Diff view
47 Displays changes made in a particular commit.
48 .It Blame view
49 Displays the line-by-line history of a file.
50 .It Tree view
51 Displays the tree corresponding to a particular commit.
52 .It Ref view
53 Displays references in the repository.
54 .El
55 .Pp
56 .Nm
57 provides global and command-specific key bindings and options.
58 The global key bindings are:
59 .Bl -tag -width Ds
60 .It Cm Q
61 Quit
62 .Nm .
63 .It Cm q
64 Quit the view which is in focus.
65 .It Cm Tab
66 Switch focus between views.
67 .It Cm f
68 Toggle fullscreen mode for a split-screen view.
69 .Nm
70 will automatically use split-screen views if the size of the terminal
71 window is sufficiently large.
72 .El
73 .Pp
74 Global options must precede the command name, and are as follows:
75 .Bl -tag -width tenletters
76 .It Fl h
77 Display usage information.
78 .It Fl V , -version
79 Display program version and exit immediately.
80 .El
81 .Pp
82 The commands for
83 .Nm
84 are as follows:
85 .Bl -tag -width blame
86 .It Cm log Oo Fl b Oc Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
87 Display history of a repository.
88 If a
89 .Ar path
90 is specified, show only commits which modified this path.
91 If invoked in a work tree, the
92 .Ar path
93 is interpreted relative to the current working directory,
94 and the work tree's path prefix is implicitly prepended.
95 Otherwise, the path is interpreted relative to the repository root.
96 .Pp
97 This command is also executed if no explicit command is specified.
98 .Pp
99 The key bindings for
100 .Cm tog log
101 are as follows:
102 .Bl -tag -width Ds
103 .It Cm Down-arrow, j, >, Full stop, Ctrl-n
104 Move the selection cursor down.
105 .It Cm Up-arrow, k, <, Comma, Ctrl-p
106 Move the selection cursor up.
107 .It Cm Page-down, Ctrl+f
108 Move the selection cursor down one page.
109 .It Cm Page-up, Ctrl+b
110 Move the selection cursor up one page.
111 .It Cm Home, g
112 Move the cursor to the newest commit.
113 .It Cm End, G
114 Move the cursor to the oldest commit.
115 This will traverse all commits on the current branch which may take
116 a long time depending on the number of commits in branch history.
117 If needed, this operation can be cancelled with
118 .Cm Backspace .
119 .It Cm Enter, Space
120 Open a
121 .Cm diff
122 view showing file changes made in the currently selected commit.
123 .It Cm t
124 Open a
125 .Cm tree
126 view showing the tree for the currently selected commit.
127 .It Cm Backspace
128 Show log entries for the parent directory of the currently selected path.
129 However when an active search is in progress or when additional commits
130 are loaded,
131 .Cm Backspace
132 aborts the running operation.
133 .It Cm /
134 Prompt for a search pattern and start searching for matching commits.
135 The search pattern is an extended regular expression which is matched
136 against a commit's author name, committer name, log message, and
137 commit ID SHA1 hash.
138 Regular expression syntax is documented in
139 .Xr re_format 7 .
140 .It Cm n
141 Find the next commit which matches the current search pattern.
142 Searching continues until either a match is found or the
143 .Cm Backspace
144 key is pressed.
145 .It Cm N
146 Find the previous commit which matches the current search pattern.
147 Searching continues until either a match is found or the
148 .Cm Backspace
149 key is pressed.
150 .It Cm Ctrl+l
151 Reload the
152 .Cm log
153 view with new commits found in the repository.
154 .It Cm B
155 Reload the
156 .Cm log
157 view and toggle display of merged commits.
158 The
159 .Fl b
160 option determines whether merged commits are displayed initially.
161 .It Cm r
162 Open a
163 .Cm ref
164 view listing all references in the repository.
165 This can then be used to open a new
166 .Cm log
167 view for arbitrary branches and tags.
168 .El
169 .Pp
170 The options for
171 .Cm tog log
172 are as follows:
173 .Bl -tag -width Ds
174 .It Fl b
175 Display individual commits which were merged into the current branch
176 from other branches.
177 By default,
178 .Cm tog log
179 shows the linear history of the current branch only.
180 The
181 .Cm B
182 key binding can be used to toggle display of merged commits at run-time.
183 .It Fl c Ar commit
184 Start traversing history at the specified
185 .Ar commit .
186 The expected argument is the name of a branch or a commit ID SHA1 hash.
187 An abbreviated hash argument will be expanded to a full SHA1 hash
188 automatically, provided the abbreviation is unique.
189 If this option is not specified, default to the work tree's current branch
190 if invoked in a work tree, or to the repository's HEAD reference.
191 .It Fl r Ar repository-path
192 Use the repository at the specified path.
193 If not specified, assume the repository is located at or above the current
194 working directory.
195 If this directory is a
196 .Xr got 1
197 work tree, use the repository path associated with this work tree.
198 .El
199 .It Cm diff Oo Fl a Oc Oo Fl C Ar number Oc Oo Fl r Ar repository-path Oc Oo Fl w Oc Ar object1 Ar object2
200 Display the differences between two objects in the repository.
201 Treat each of the two arguments as a reference, a tag name, or an object
202 ID SHA1 hash, and display differences between the corresponding objects.
203 Both objects must be of the same type (blobs, trees, or commits).
204 An abbreviated hash argument will be expanded to a full SHA1 hash
205 automatically, provided the abbreviation is unique.
206 .Pp
207 The key bindings for
208 .Cm tog diff
209 are as follows:
210 .Bl -tag -width Ds
211 .It Cm a
212 Toggle treatment of file contents as ASCII text even if binary data was
213 detected.
214 .It Cm Down-arrow, j, Ctrl-n
215 Scroll down.
216 .It Cm Up-arrow, k, Ctrl-p
217 Scroll up.
218 .It Cm Page-down, Space, Ctrl+f
219 Scroll down one page.
220 .It Cm Page-up, Ctrl+b
221 Scroll up one page.
222 .It Cm Home, g
223 Scroll to the top of the view.
224 .It Cm End, G
225 Scroll to the bottom of the view.
226 .It Cm \&[
227 Reduce the amount of diff context lines.
228 .It Cm \&]
229 Increase the amount of diff context lines.
230 .It Cm <, Comma
231 If the
232 .Cm diff
233 view was opened via the
234 .Cm log
235 view, move to the previous (younger) commit.
236 .It Cm >, Full stop
237 If the
238 .Cm diff
239 view was opened via the
240 .Cm log
241 view, move to the next (older) commit.
242 .It Cm /
243 Prompt for a search pattern and start searching for matching lines.
244 The search pattern is an extended regular expression.
245 Regular expression syntax is documented in
246 .Xr re_format 7 .
247 .It Cm n
248 Find the next line which matches the current search pattern.
249 .It Cm N
250 Find the previous line which matches the current search pattern.
251 .It Cm w
252 Toggle display of whitespace-only changes.
253 .El
254 .Pp
255 The options for
256 .Cm tog diff
257 are as follows:
258 .Bl -tag -width Ds
259 .It Fl a
260 Treat file contents as ASCII text even if binary data is detected.
261 .It Fl C Ar number
262 Set the number of context lines shown in the diff.
263 By default, 3 lines of context are shown.
264 .It Fl r Ar repository-path
265 Use the repository at the specified path.
266 If not specified, assume the repository is located at or above the current
267 working directory.
268 If this directory is a
269 .Xr got 1
270 work tree, use the repository path associated with this work tree.
271 .It Fl w
272 Ignore whitespace-only changes.
273 .El
274 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
275 Display line-by-line history of a file at the specified path.
276 .Pp
277 The key bindings for
278 .Cm tog blame
279 are as follows:
280 .Bl -tag -width Ds
281 .It Cm Down-arrow, j, Ctrl-n
282 Move the selection cursor down.
283 .It Cm Up-arrow, k, Ctrl-p
284 Move the selection cursor up.
285 .It Cm Page-down, Space, Ctrl+f
286 Move the selection cursor down one page.
287 .It Cm Page-up, Ctrl+b
288 Move the selection cursor up one page.
289 .It Cm Home, g
290 Move the selection cursor to the first line of the file.
291 .It Cm End, G
292 Move the selection cursor to the last line of the file.
293 .It Cm Enter
294 Open a
295 .Cm diff
296 view for the currently selected line's commit.
297 .It Cm b
298 Reload the
299 .Cm blame
300 view with the version of the file as found in the currently
301 selected line's commit.
302 .It Cm p
303 Reload the
304 .Cm blame
305 view with the version of the file as found in the parent commit of the
306 currently selected line's commit.
307 .It Cm B
308 Reload the
309 .Cm blame
310 view with the previously blamed commit.
311 .It Cm /
312 Prompt for a search pattern and start searching for matching lines.
313 The search pattern is an extended regular expression.
314 Regular expression syntax is documented in
315 .Xr re_format 7 .
316 .It Cm n
317 Find the next line which matches the current search pattern.
318 .It Cm N
319 Find the previous line which matches the current search pattern.
320 .El
321 .Pp
322 The options for
323 .Cm tog blame
324 are as follows:
325 .Bl -tag -width Ds
326 .It Fl c Ar commit
327 Start traversing history at the specified
328 .Ar commit .
329 The expected argument is the name of a branch or a commit ID SHA1 hash.
330 An abbreviated hash argument will be expanded to a full SHA1 hash
331 automatically, provided the abbreviation is unique.
332 .It Fl r Ar repository-path
333 Use the repository at the specified path.
334 If not specified, assume the repository is located at or above the current
335 working directory.
336 If this directory is a
337 .Xr got 1
338 work tree, use the repository path associated with this work tree.
339 .El
340 .It Cm tree Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
341 Display the repository tree.
342 If a
343 .Ar path
344 is specified, show tree entries at this path.
345 .Pp
346 Displayed tree entries may carry one of the following trailing annotations:
347 .Bl -column YXZ description
348 .It @ Ta entry is a symbolic link
349 .It / Ta entry is a directory
350 .It * Ta entry is an executable file
351 .It $ Ta entry is a Git submodule
352 .El
353 .Pp
354 Symbolic link entries are also annotated with the target path of the link.
355 .Pp
356 The key bindings for
357 .Cm tog tree
358 are as follows:
359 .Bl -tag -width Ds
360 .It Cm Down-arrow, j, Ctrl-n
361 Move the selection cursor down.
362 .It Cm Up-arrow, k, Ctrl-p
363 Move the selection cursor up.
364 .It Cm Page-down, Ctrl+f
365 Move the selection cursor down one page.
366 .It Cm Page-up, Ctrl+b
367 Move the selection cursor up one page.
368 .It Cm Home, g
369 Move the selection cursor to the first entry.
370 .It Cm End, G
371 Move the selection cursor to the last entry.
372 .It Cm Enter
373 Enter the currently selected directory, or switch to the
374 .Cm blame
375 view for the currently selected file.
376 .It Cm l
377 Open a
378 .Cm log
379 view for the currently selected tree entry.
380 .It Cm r
381 Open a
382 .Cm ref
383 view listing all references in the repository.
384 This can then be used to open a new
385 .Cm tree
386 view for arbitrary branches and tags.
387 .It Cm Backspace
388 Move back to the parent directory.
389 .It Cm i
390 Show object IDs for all objects displayed in the
391 .Cm tree
392 view.
393 .It Cm /
394 Prompt for a search pattern and start searching for matching tree entries.
395 The search pattern is an extended regular expression which is matched
396 against the tree entry's name.
397 Regular expression syntax is documented in
398 .Xr re_format 7 .
399 .It Cm n
400 Find the next tree entry which matches the current search pattern.
401 .It Cm N
402 Find the previous tree entry which matches the current search pattern.
403 .El
404 .Pp
405 The options for
406 .Cm tog tree
407 are as follows:
408 .Bl -tag -width Ds
409 .It Fl c Ar commit
410 Start traversing history at the specified
411 .Ar commit .
412 The expected argument is the name of a branch or a commit ID SHA1 hash.
413 An abbreviated hash argument will be expanded to a full SHA1 hash
414 automatically, provided the abbreviation is unique.
415 .It Fl r Ar repository-path
416 Use the repository at the specified path.
417 If not specified, assume the repository is located at or above the current
418 working directory.
419 If this directory is a
420 .Xr got 1
421 work tree, use the repository path associated with this work tree.
422 .El
423 .It Cm ref Oo Fl r Ar repository-path Oc
424 Display references in the repository.
425 .Pp
426 The key bindings for
427 .Cm tog ref
428 are as follows:
429 .Bl -tag -width Ds
430 .It Cm Down-arrow, j, Ctrl-n
431 Move the selection cursor down.
432 .It Cm Up-arrow, k, Ctrl-p
433 Move the selection cursor up.
434 .It Cm Page-down, Ctrl+f
435 Move the selection cursor down one page.
436 .It Cm Page-up, Ctrl+b
437 Move the selection cursor up one page.
438 .It Cm Home, g
439 Move the selection cursor to the first reference.
440 .It Cm End, G
441 Move the selection cursor to the last reference.
442 .It Cm Enter
443 Open a
444 .Cm log
445 view which begins traversing history at the commit resolved via the
446 currently selected reference.
447 .It Cm t
448 Open a
449 .Cm tree
450 view showing the tree resolved via the currently selected reference.
451 .It Cm i
452 Show object IDs for all non-symbolic references displayed in the
453 .Cm ref
454 view.
455 .It Cm o
456 Toggle display order of references between sort by name and sort by timestamp.
457 .It Cm /
458 Prompt for a search pattern and start searching for matching references.
459 The search pattern is an extended regular expression which is matched
460 against absolute reference names.
461 Regular expression syntax is documented in
462 .Xr re_format 7 .
463 .It Cm n
464 Find the next reference which matches the current search pattern.
465 .It Cm N
466 Find the previous reference which matches the current search pattern.
467 .It Cm Ctrl+l
468 Reload the list of references displayed by the
469 .Cm ref
470 view.
471 .El
472 .Pp
473 The options for
474 .Cm tog ref
475 are as follows:
476 .Bl -tag -width Ds
477 .It Fl r Ar repository-path
478 Use the repository at the specified path.
479 If not specified, assume the repository is located at or above the current
480 working directory.
481 If this directory is a
482 .Xr got 1
483 work tree, use the repository path associated with this work tree.
484 .El
485 .El
486 .Sh ENVIRONMENT
487 .Bl -tag -width TOG_COLORS
488 .It Ev TOG_COLORS
489 .Nm
490 shows colorized output if this variable is set to a non-empty value.
491 The default color scheme can be modified by setting the environment
492 variables documented below.
493 The colors available in color schemes are
494 .Dq black ,
495 .Dq red ,
496 .Dq green ,
497 .Dq yellow ,
498 .Dq blue ,
499 .Dq magenta ,
500 .Dq cyan ,
501 and
502 .Dq default
503 which maps to the terminal's default foreground color.
504 .It Ev TOG_COLOR_DIFF_MINUS
505 The color used to mark up removed lines in diffs.
506 If not set, the default value
507 .Dq magenta
508 is used.
509 .It Ev TOG_COLOR_DIFF_PLUS
510 The color used to mark up added lines in diffs.
511 If not set, the default value
512 .Dq cyan
513 is used.
514 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
515 The color used to mark up chunk header lines in diffs.
516 If not set, the default value
517 .Dq yellow
518 is used.
519 .It Ev TOG_COLOR_DIFF_META
520 The color used to mark up meta data in diffs.
521 If not set, the default value
522 .Dq green
523 is used.
524 .It Ev TOG_COLOR_TREE_SUBMODULE
525 The color used to mark up submodule tree entries.
526 If not set, the default value
527 .Dq magenta
528 is used.
529 .It Ev TOG_COLOR_TREE_SYMLINK
530 The color used to mark up symbolic link tree entries.
531 If not set, the default value
532 .Dq magenta
533 is used.
534 .It Ev TOG_COLOR_TREE_DIRECTORY
535 The color used to mark up directory tree entries.
536 If not set, the default value
537 .Dq cyan
538 is used.
539 .It Ev TOG_COLOR_TREE_EXECUTABLE
540 The color used to mark up executable file tree entries.
541 If not set, the default value
542 .Dq green
543 is used.
544 .It Ev TOG_COLOR_COMMIT
545 The color used to mark up commit IDs.
546 If not set, the default value
547 .Dq green
548 is used.
549 .It Ev TOG_COLOR_AUTHOR
550 The color used to mark up author information.
551 If not set, the default value
552 .Dq cyan
553 is used.
554 .It Ev TOG_COLOR_DATE
555 The color used to mark up date information.
556 If not set, the default value
557 .Dq yellow
558 is used.
559 .It Ev TOG_COLOR_REFS_HEADS
560 The color used to mark up references in the
561 .Dq refs/heads/
562 namespace.
563 If not set, the default value
564 .Dq green
565 is used.
566 .It Ev TOG_COLOR_REFS_TAGS
567 The color used to mark up references in the
568 .Dq refs/tags/
569 namespace.
570 If not set, the default value
571 .Dq magenta
572 is used.
573 .It Ev TOG_COLOR_REFS_REMOTES
574 The color used to mark up references in the
575 .Dq refs/remotes/
576 namespace.
577 If not set, the default value
578 .Dq yellow
579 is used.
580 .It Ev TOG_COLOR_REFS_BACKUP
581 The color used to mark up references in the
582 .Dq refs/got/backup/
583 namespace.
584 If not set, the default value
585 .Dq cyan
586 is used.
587 .El
588 .Sh EXIT STATUS
589 .Ex -std tog
590 .Sh SEE ALSO
591 .Xr got 1 ,
592 .Xr git-repository 5 ,
593 .Xr re_format 7
594 .Sh AUTHORS
595 .An Stefan Sperling Aq Mt stsp@openbsd.org
596 .An Joshua Stein Aq Mt jcs@openbsd.org