| blob | 12fb6a296691f5f6e253d1bb7b61e721bb020312 |
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 Fl hV
25 .Ar command
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 work tree changes or 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 Some command-specific key bindings may be prefixed with an integer, which is
59 denoted by N in the descriptions below, and is used as a modifier to the
60 operation as indicated.
61 .Nm
62 will echo digits to the screen when count modifiers are entered, and complete
63 the sequence upon input of the first non-numeric character.
64 Count modifiers can be aborted by entering an unmapped key.
65 Once a compound command is executed, the operation can be cancelled with
66 .Cm C-g
67 or
68 .Cm Backspace .
69 .Pp
70 Global options must precede the command name, and are as follows:
71 .Bl -tag -width tenletters
72 .It Fl h
73 Display usage information.
74 .It Fl V , -version
75 Display program version and exit immediately.
76 .El
77 .Pp
78 The global key bindings are:
79 .Bl -tag -width Ds
80 .It Cm H, F1
81 Display run-time help.
82 Key bindings for the focussed view will be displayed.
83 Pressing this again inside the help view will toggle the display of
84 key bindings for all
85 .Nm
86 views.
87 .It Cm Q
88 Quit
89 .Nm .
90 .It Cm q
91 Quit the view which is in focus.
92 .It Cm Tab
93 Switch focus between views.
94 .It Cm F
95 Toggle fullscreen mode for a split-screen view.
96 .Nm
97 will automatically use vertical split-screen views if the size of the
98 terminal window is sufficiently large.
99 .It Cm S
100 Switch the current split-screen layout, and render all active views in
101 this new layout.
102 The split-screen layout can be either vertical or horizontal.
103 If the terminal is not wide enough when switching to a vertical split,
104 views will render in fullscreen.
105 .It Cm -
106 When in a split-screen view, decrease the size of the focussed split
107 N increments (default: 1).
108 .It Cm +
109 When in a split-screen view, increase the size of the focussed split
110 N increments (default: 1).
111 .It Cm G
112 Go to line N in the view (default: last line).
113 .It Cm g
114 Go to line N in the view (default: first line).
115 .It Cm Right-arrow, l
116 Scroll view to the right N increments (default: 1).
117 .br
118 Output moves left on the screen.
119 .It Cm Left-arrow, h
120 Scroll view to the left N increments (default: 1).
121 .br
122 Output moves right on the screen.
123 .It Cm $
124 Scroll view to the rightmost position.
125 .It Cm 0
126 Scroll view left to the start of the line.
127 .El
128 .Pp
129 The commands for
130 .Nm
131 are as follows:
132 .Bl -tag -width blame
133 .It Xo
134 .Cm log
135 .Op Fl b
136 .Op Fl c Ar commit
137 .Op Fl r Ar repository-path
138 .Op Ar path
139 .Xc
140 Display history of a repository.
141 If a
142 .Ar path
143 is specified, show only commits which modified this path.
144 If invoked in a work tree, the
145 .Ar path
146 is interpreted relative to the current working directory,
147 and the work tree's path prefix is implicitly prepended.
148 Otherwise, the path is interpreted relative to the repository root.
149 .Pp
150 If invoked in a work tree, the log entry of the work tree's base commit will
151 be prefixed with one of the following annotations:
152 .Bl -column YXZ description
153 .It * Ta work tree's base commit and the base commit of all tracked files
154 matches the branch tip
155 .It \(a~ Ta work tree comprises mixed commits or its base commit is out-of-date
156 .El
157 .Pp
158 This command is also executed if no explicit command is specified.
159 .Pp
160 The key bindings for
161 .Cm tog log
162 are as follows (N denotes optional prefixed count modifier):
163 .Bl -tag -width Ds
164 .It Cm Down-arrow, j, >, Full stop, Ctrl-n
165 Move the selection cursor down N lines (default: 1).
166 .It Cm Up-arrow, k, <, Comma, Ctrl-p
167 Move the selection cursor up N lines (default: 1).
168 .It Cm Page-down, Space, Ctrl+f, f
169 Move the selection cursor down N pages (default: 1).
170 .It Cm Page-up, Ctrl+b, b
171 Move the selection cursor up N pages (default: 1).
172 .It Cm Ctrl+d, d
173 Move the selection cursor down N half pages (default: 1).
174 .It Cm Ctrl+u, u
175 Move the selection cursor up N half pages (default: 1).
176 .It Cm Home, =
177 Move the cursor to the newest commit.
178 .It Cm End, *
179 Move the cursor to the oldest commit.
180 This will traverse all commits on the current branch which may take
181 a long time depending on the number of commits in branch history.
182 If needed, this operation can be cancelled with
183 .Cm C-g
184 or
185 .Cm Backspace .
186 .It Cm g
187 Move the cursor to commit N (default: 1).
188 .It Cm G
189 Like
190 .Cm g
191 but defaults to the oldest commit.
192 .It Cm Enter
193 Open a
194 .Cm diff
195 view showing file changes made in the currently selected commit.
196 If a commit is marked with the
197 .Cm m
198 key map, open a diff view showing file changes made between the marked commit
199 and the currently selected commit.
200 .It Cm m
201 Mark or unmark the selected commit.
202 When a commit is marked,
203 pressing the
204 .Cm enter
205 key on another selected commit opens a
206 .Cm diff
207 view showing the changes between the marked commit and the
208 currently selected commit.
209 .It Cm T
210 Open a
211 .Cm tree
212 view showing the tree for the currently selected commit.
213 .It Cm Backspace
214 Show log entries for the parent directory of the currently selected path.
215 However when an active search is in progress or when additional commits
216 are loaded,
217 .Cm Backspace
218 aborts the running operation.
219 .It Cm /
220 Prompt for a search pattern and start searching for matching commits.
221 The search pattern is an extended regular expression which is matched
222 against a commit's author name, committer name, log message, and
223 commit ID.
224 Regular expression syntax is documented in
225 .Xr re_format 7 .
226 .It Cm &
227 Prompt for a pattern and limit the log view's list of commits to those
228 which match the pattern.
229 If no pattern is specified, i.e. the
230 .Cm &
231 prompt is immediately closed with the Enter key, then the pattern is
232 cleared.
233 Until the pattern is cleared, the limited list of commits replaces the
234 full list of commits for all operations supported by the log view.
235 For example, a search started with
236 .Cm /
237 will search the limited list of commits, rather than searching all commits.
238 The pattern is an extended regular expression which is matched
239 against a commit's author name, committer name, log message, and
240 commit ID.
241 Regular expression syntax is documented in
242 .Xr re_format 7 .
243 .It Cm n
244 Find the Nth next commit which matches the current search pattern (default: 1).
245 .br
246 Searching continues until either a match is found or
247 .Cm C-g
248 or the
249 .Cm Backspace
250 key is pressed.
251 .It Cm N
252 Find the Nth previous commit which matches the current search pattern
253 (default: 1).
254 .br
255 Searching continues until either a match is found or
256 .Cm C-g
257 or the
258 .Cm Backspace
259 key is pressed.
260 .It Cm Ctrl+l
261 Reload the
262 .Cm log
263 view with new commits found in the repository or new work tree changes.
264 .It Cm B
265 Reload the
266 .Cm log
267 view and toggle display of merged commits.
268 The
269 .Fl b
270 option determines whether merged commits are displayed initially.
271 .It Cm R
272 Open a
273 .Cm ref
274 view listing all references in the repository.
275 This can then be used to open a new
276 .Cm log
277 view for arbitrary branches and tags.
278 .It Cm @
279 Toggle between showing the committer name and the author name.
280 .El
281 .Pp
282 The options for
283 .Cm tog log
284 are as follows:
285 .Bl -tag -width Ds
286 .It Fl b
287 Display individual commits which were merged into the current branch
288 from other branches.
289 By default,
290 .Cm tog log
291 shows the linear history of the current branch only.
292 The
293 .Cm B
294 key binding can be used to toggle display of merged commits at run-time.
295 .It Fl c Ar commit
296 Start traversing history at the specified
297 .Ar commit .
298 The expected argument is a commit ID, or a reference name or keyword
299 which will be resolved to a commit ID.
300 An abbreviated hash argument will be expanded to a full commit ID
301 automatically, provided the abbreviation is unique.
302 The keywords
303 .Qq :base
304 and
305 .Qq :head
306 resolve to the work tree's base commit and branch head, respectively.
307 The former is only valid if invoked in a work tree, while the latter will
308 resolve to the tip of the work tree's current branch if invoked in a
309 work tree, otherwise it will resolve to the repository's HEAD reference.
310 Keywords and references may be appended with
311 .Qq :+
312 or
313 .Qq :-
314 modifiers and an optional integer N to denote the
315 Nth descendant or antecedent by first parent traversal, respectively;
316 for example,
317 .Sy :head:-2
318 denotes the work tree branch head's 2nd generation ancestor, and
319 .Sy :base:+4
320 denotes the 4th generation descendant of the work tree's base commit.
321 Similarly,
322 .Sy foobar:+3
323 will denote the 3rd generation descendant of the commit resolved by the
324 .Qq foobar
325 reference.
326 A
327 .Qq :+
328 or
329 .Qq :-
330 modifier without a trailing integer has an implicit
331 .Qq 1
332 appended
333 .Po e.g.,
334 .Sy :base:+
335 is equivalent to
336 .Sy :base:+1
337 .Pc .
338 .It Fl r Ar repository-path
339 Use the repository at the specified path.
340 If not specified, assume the repository is located at or above the current
341 working directory.
342 If this directory is a
343 .Xr got 1
344 work tree, use the repository path associated with this work tree.
345 .El
346 .It Xo
347 .Cm diff
348 .Op Fl asw
349 .Op Fl C Ar number
350 .Op Fl c Ar commit
351 .Op Fl r Ar repository-path
352 .Op Ar object1 Ar object2 | Ar path ...
353 .Xc
354 If invoked within a work tree without any arguments, display all local
355 changes in the work tree.
356 If one or more
357 .Ar path
358 arguments are specified, only show changes within the specified paths.
359 .Pp
360 Alternatively, if two object arguments are specified, display the differences
361 between the two objects in the repository.
362 Treat each of the two arguments as a reference, a tag name, an object
363 ID, or a keyword and display differences between the corresponding
364 objects.
365 Both objects must be of the same type (blobs, trees, or commits).
366 An abbreviated hash argument will be expanded to a full commit ID
367 automatically, provided the abbreviation is unique.
368 The keywords
369 .Qq :base
370 and
371 .Qq :head
372 resolve to the work tree's base commit and branch head, respectively.
373 The former is only valid if invoked in a work tree, while the latter will
374 resolve to the tip of the work tree's current branch if invoked in a
375 work tree, otherwise it will resolve to the repository's HEAD reference.
376 Keywords and references may be appended with
377 .Qq :+
378 or
379 .Qq :-
380 modifiers and an optional integer N to denote the
381 Nth descendant or antecedent by first parent traversal, respectively;
382 for example,
383 .Sy :head:-2
384 denotes the work tree branch head's 2nd generation ancestor, and
385 .Sy :base:+4
386 denotes the 4th generation descendant of the work tree's base commit.
387 Similarly,
388 .Sy foobar:+3
389 will denote the 3rd generation descendant of the commit resolved by the
390 .Qq foobar
391 reference.
392 A
393 .Qq :+
394 or
395 .Qq :-
396 modifier without a trailing integer has an implicit
397 .Qq 1
398 appended
399 .Po e.g.,
400 .Sy :base:+
401 is equivalent to
402 .Sy :base:+1
403 .Pc .
404 .Pp
405 The key bindings for
406 .Cm tog diff
407 are as follows (N denotes optional prefixed count modifier):
408 .Bl -tag -width Ds
409 .It Cm a
410 Toggle treatment of file contents as ASCII text even if binary data was
411 detected.
412 .It Cm Down-arrow, j, Ctrl-n
413 Scroll down N lines (default: 1).
414 .It Cm Up-arrow, k, Ctrl-p
415 Scroll up N lines (default: 1).
416 .It Cm Page-down, Space, Ctrl+f, f
417 Scroll down N pages (default: 1).
418 .It Cm Page-up, Ctrl+b, b
419 Scroll up N pages (default: 1).
420 .It Cm Ctrl+d, d
421 Scroll down N half pages (default: 1).
422 .It Cm Ctrl+u, u
423 Scroll up N half pages (default: 1).
424 .It Cm Home
425 Scroll to the top of the view.
426 .It Cm End
427 Scroll to the bottom of the view.
428 .It Cm g
429 Scroll to line N (default: 1).
430 .It Cm G
431 Like
432 .Cm g
433 but defaults to the last line in the diff.
434 .It Cm \&(
435 Navigate to the Nth previous file in the diff (default: 1).
436 .It Cm \&)
437 Navigate to the Nth next file in the diff (default: 1).
438 .It Cm \&{
439 Navigate to the Nth previous hunk in the diff (default: 1).
440 .It Cm \&}
441 Navigate to the Nth next hunk in the diff (default: 1).
442 .It Cm \&[
443 Reduce diff context by N lines (default: 1).
444 .It Cm \&]
445 Increase diff context by N lines (default: 1).
446 .It Cm <, Comma, K
447 If the
448 .Cm diff
449 view was opened via the
450 .Cm log
451 view, move to the Nth previous (younger) commit.
452 If the diff was opened via the
453 .Cm blame
454 view, move to the Nth previous line and load the corresponding commit
455 (default: 1).
456 .It Cm >, Full stop, J
457 If the
458 .Cm diff
459 view was opened via the
460 .Cm log
461 view, move to the Nth next (older) commit.
462 If the diff was opened via the
463 .Cm blame
464 view, move to the Nth next line and load the corresponding commit (default: 1).
465 .It Cm p
466 Write the currently viewed diff to a patch file in
467 .Pa /tmp .
468 The patch pathname is drawn to the status line.
469 .It Cm /
470 Prompt for a search pattern and start searching for matching lines.
471 The search pattern is an extended regular expression.
472 Regular expression syntax is documented in
473 .Xr re_format 7 .
474 .It Cm n
475 Find the Nth next line which matches the current search pattern (default: 1).
476 .It Cm N
477 Find the Nth previous line which matches the current search pattern
478 (default: 1).
479 .It Cm w
480 Toggle display of whitespace-only changes.
481 .It Cm A
482 Change the diff algorithm.
483 Supported diff algorithms are Myers (quick and dirty) and
484 Patience (slow and tidy).
485 This is a global setting which also affects the
486 .Cm blame
487 view.
488 .El
489 .Pp
490 The options for
491 .Cm tog diff
492 are as follows:
493 .Bl -tag -width Ds
494 .It Fl a
495 Treat file contents as ASCII text even if binary data is detected.
496 .It Fl C Ar number
497 Set the number of context lines shown in the diff.
498 By default, 3 lines of context are shown.
499 .It Fl c Ar commit
500 Show differences between commits in the repository.
501 This option may be used up to two times.
502 When used only once, show differences between the specified
503 .Ar commit
504 and its first parent commit.
505 When used twice, show differences between the two specified commits.
506 .Pp
507 The expected argument is a commit ID hash, or an existing reference,
508 tag name, or keyword, which is resolved to a commit ID.
509 Unique abbreviated hash arguments are automatically expanded to a full hash.
510 Both objects must be of the same type (i.e., blobs, trees, or commits).
511 .Pp
512 If the
513 .Fl c
514 option is used, all non-option arguments are interpreted as paths.
515 If one or more such
516 .Ar path
517 arguments are provided, only show differences for the specified paths.
518 .It Fl r Ar repository-path
519 Use the repository at the specified path.
520 If not specified, assume the repository is located at or above the current
521 working directory.
522 If this directory is a
523 .Xr got 1
524 work tree, use the repository path associated with this work tree.
525 .It Fl s
526 Show changes staged with
527 .Cm got stage
528 instead of showing local changes in the work tree.
529 This option is only valid when
530 .Cm tog diff
531 is invoked in a work tree with no
532 .Fl c
533 options.
534 .It Fl w
535 Ignore whitespace-only changes.
536 .El
537 .It Xo
538 .Cm blame
539 .Op Fl c Ar commit
540 .Op Fl r Ar repository-path
541 .Ar path
542 .Xc
543 Display line-by-line history of a file at the specified path.
544 .Pp
545 The key bindings for
546 .Cm tog blame
547 are as follows (N denotes optional prefixed count modifier):
548 .Bl -tag -width Ds
549 .It Cm Down-arrow, j, Ctrl-n
550 Move the selection cursor down N pages (default: 1).
551 .It Cm Up-arrow, k, Ctrl-p
552 Move the selection cursor up N pages (default: 1).
553 .It Cm Page-down, Space, Ctrl+f, f
554 Move the selection cursor down N pages (default: 1).
555 .It Cm Page-up, Ctrl+b, b
556 Move the selection cursor up N pages (default: 1).
557 .It Cm Ctrl+d, d
558 Move the selection cursor down N half pages (default: 1).
559 .It Cm Ctrl+u, u
560 Move the selection cursor up N half pages (default: 1).
561 .It Cm Home
562 Move the selection cursor to the first line of the file.
563 .It Cm End
564 Move the selection cursor to the last line of the file.
565 .It Cm g
566 Move the selection cursor to line N (default: 1).
567 .It Cm G
568 Like
569 .Cm g
570 but defaults to the last line in the file.
571 .It Cm Enter
572 Open a
573 .Cm diff
574 view for the currently selected line's commit.
575 .It Cm c
576 Reload the
577 .Cm blame
578 view with the version of the file as found in the currently
579 selected line's commit.
580 .It Cm p
581 Reload the
582 .Cm blame
583 view with the version of the file as found in the parent commit of the
584 currently selected line's commit.
585 .It Cm C
586 Reload the
587 .Cm blame
588 view with the previously blamed commit.
589 .It Cm L
590 Open a
591 .Cm log
592 view for the currently selected annotated line.
593 .It Cm /
594 Prompt for a search pattern and start searching for matching lines.
595 The search pattern is an extended regular expression.
596 Regular expression syntax is documented in
597 .Xr re_format 7 .
598 .It Cm n
599 Find the Nth next line which matches the current search pattern (default: 1).
600 .It Cm N
601 Find the Nth previous line which matches the current search pattern
602 (default: 1).
603 .It Cm A
604 Change the diff algorithm.
605 Supported diff algorithms are Myers (quick and dirty) and
606 Patience (slow and tidy).
607 This is a global setting which also affects the
608 .Cm diff
609 view.
610 .El
611 .Pp
612 The options for
613 .Cm tog blame
614 are as follows:
615 .Bl -tag -width Ds
616 .It Fl c Ar commit
617 Start traversing history at the specified
618 .Ar commit .
619 The expected argument is a commit ID, or a reference name or keyword
620 which will be resolved to a commit ID.
621 An abbreviated hash argument will be expanded to a full commit ID
622 automatically, provided the abbreviation is unique.
623 The keywords
624 .Qq :base
625 and
626 .Qq :head
627 resolve to the work tree's base commit and branch head, respectively.
628 The former is only valid if invoked in a work tree, while the latter will
629 resolve to the tip of the work tree's current branch if invoked in a
630 work tree, otherwise it will resolve to the repository's HEAD reference.
631 Keywords and references may be appended with
632 .Qq :+
633 or
634 .Qq :-
635 modifiers and an optional integer N to denote the
636 Nth descendant or antecedent by first parent traversal, respectively;
637 for example,
638 .Sy :head:-2
639 denotes the work tree branch head's 2nd generation ancestor, and
640 .Sy :base:+4
641 denotes the 4th generation descendant of the work tree's base commit.
642 Similarly,
643 .Sy foobar:+3
644 will denote the 3rd generation descendant of the commit resolved by the
645 .Qq foobar
646 reference.
647 A
648 .Qq :+
649 or
650 .Qq :-
651 modifier without a trailing integer has an implicit
652 .Qq 1
653 appended
654 .Po e.g.,
655 .Sy :base:+
656 is equivalent to
657 .Sy :base:+1
658 .Pc .
659 .It Fl r Ar repository-path
660 Use the repository at the specified path.
661 If not specified, assume the repository is located at or above the current
662 working directory.
663 If this directory is a
664 .Xr got 1
665 work tree, use the repository path associated with this work tree.
666 .El
667 .It Xo
668 .Cm tree
669 .Op Fl c Ar commit
670 .Op Fl r Ar repository-path
671 .Op Ar path
672 .Xc
673 Display the repository tree.
674 If a
675 .Ar path
676 is specified, show tree entries at this path.
677 .Pp
678 Displayed tree entries may carry one of the following trailing annotations:
679 .Bl -column YXZ description
680 .It @ Ta entry is a symbolic link
681 .It / Ta entry is a directory
682 .It * Ta entry is an executable file
683 .It $ Ta entry is a Git submodule
684 .El
685 .Pp
686 Symbolic link entries are also annotated with the target path of the link.
687 .Pp
688 The key bindings for
689 .Cm tog tree
690 are as follows (N denotes optional prefixed count modifier):
691 .Bl -tag -width Ds
692 .It Cm Down-arrow, j, Ctrl-n
693 Move the selection cursor down N lines (default: 1).
694 .It Cm Up-arrow, k, Ctrl-p
695 Move the selection cursor up N lines (default: 1).
696 .It Cm Page-down, Space, Ctrl+f, f
697 Move the selection cursor down N pages (default: 1).
698 .It Cm Page-up, Ctrl+b, b
699 Move the selection cursor up N pages (default: 1).
700 .It Cm Ctrl+d, d
701 Move the selection cursor down N half pages (default: 1).
702 .It Cm Ctrl+u, u
703 Move the selection cursor up N half pages (default: 1).
704 .It Cm Home, =
705 Move the selection cursor to the first entry.
706 .It Cm End, *
707 Move the selection cursor to the last entry.
708 .It Cm g
709 Move the selection cursor to entry N (default: 1).
710 .It Cm G
711 Like
712 .Cm g
713 but defaults to the last entry.
714 .It Cm Enter
715 Enter the currently selected directory, or switch to the
716 .Cm blame
717 view for the currently selected file.
718 .It Cm L
719 Open a
720 .Cm log
721 view for the currently selected tree entry.
722 .It Cm R
723 Open a
724 .Cm ref
725 view listing all references in the repository.
726 This can then be used to open a new
727 .Cm tree
728 view for arbitrary branches and tags.
729 .It Cm Backspace
730 Move back to the Nth parent directory (default: 1).
731 .It Cm i
732 Show object IDs for all objects displayed in the
733 .Cm tree
734 view.
735 .It Cm /
736 Prompt for a search pattern and start searching for matching tree entries.
737 The search pattern is an extended regular expression which is matched
738 against the tree entry's name.
739 Regular expression syntax is documented in
740 .Xr re_format 7 .
741 .It Cm n
742 Find the Nth next tree entry which matches the current search pattern
743 (default: 1).
744 .It Cm N
745 Find the Nth previous tree entry which matches the current search pattern
746 (default: 1).
747 .El
748 .Pp
749 The options for
750 .Cm tog tree
751 are as follows:
752 .Bl -tag -width Ds
753 .It Fl c Ar commit
754 Start traversing history at the specified
755 .Ar commit .
756 The expected argument is a commit ID, or a reference name or keyword
757 which will be resolved to a commit ID.
758 An abbreviated hash argument will be expanded to a full commit ID
759 automatically, provided the abbreviation is unique.
760 The keywords
761 .Qq :base
762 and
763 .Qq :head
764 resolve to the work tree's base commit and branch head, respectively.
765 The former is only valid if invoked in a work tree, while the latter will
766 resolve to the tip of the work tree's current branch if invoked in a
767 work tree, otherwise it will resolve to the repository's HEAD reference.
768 Keywords and references may be appended with
769 .Qq :+
770 or
771 .Qq :-
772 modifiers and an optional integer N to denote the
773 Nth descendant or antecedent by first parent traversal, respectively;
774 for example,
775 .Sy :head:-2
776 denotes the work tree branch head's 2nd generation ancestor, and
777 .Sy :base:+4
778 denotes the 4th generation descendant of the work tree's base commit.
779 Similarly,
780 .Sy foobar:+3
781 will denote the 3rd generation descendant of the commit resolved by the
782 .Qq foobar
783 reference.
784 A
785 .Qq :+
786 or
787 .Qq :-
788 modifier without a trailing integer has an implicit
789 .Qq 1
790 appended
791 .Po e.g.,
792 .Sy :base:+
793 is equivalent to
794 .Sy :base:+1
795 .Pc .
796 .It Fl r Ar repository-path
797 Use the repository at the specified path.
798 If not specified, assume the repository is located at or above the current
799 working directory.
800 If this directory is a
801 .Xr got 1
802 work tree, use the repository path associated with this work tree.
803 .El
804 .It Cm ref Op Fl r Ar repository-path
805 Display references in the repository.
806 .Pp
807 The key bindings for
808 .Cm tog ref
809 are as follows (N denotes optional prefixed count modifier):
810 .Bl -tag -width Ds
811 .It Cm Down-arrow, j, Ctrl-n
812 Move the selection cursor down N lines (default: 1).
813 .It Cm Up-arrow, k, Ctrl-p
814 Move the selection cursor up N lines (default: 1).
815 .It Cm Page-down, Space, Ctrl+f, f
816 Move the selection cursor down N pages (default: 1).
817 .It Cm Page-up, Ctrl+b, b
818 Move the selection cursor up N pages (default: 1).
819 .It Cm Ctrl+d, d
820 Move the selection cursor down N half pages (default: 1).
821 .It Cm Ctrl+u, u
822 Move the selection cursor up N half pages (default: 1).
823 .It Cm Home, =
824 Move the selection cursor to the first reference.
825 .It Cm End, *
826 Move the selection cursor to the last reference.
827 .It Cm g
828 Move the selection cursor to reference N (default: 1).
829 .It Cm G
830 Like
831 .Cm g
832 but defaults to the last reference.
833 .It Cm Enter
834 Open a
835 .Cm log
836 view which begins traversing history at the commit resolved via the
837 currently selected reference.
838 .It Cm T
839 Open a
840 .Cm tree
841 view showing the tree resolved via the currently selected reference.
842 .It Cm i
843 Show object IDs for all non-symbolic references displayed in the
844 .Cm ref
845 view.
846 .It Cm m
847 Show last modified date of each displayed reference.
848 .It Cm o
849 Toggle display order of references between sort by name and sort by timestamp.
850 .It Cm /
851 Prompt for a search pattern and start searching for matching references.
852 The search pattern is an extended regular expression which is matched
853 against absolute reference names.
854 Regular expression syntax is documented in
855 .Xr re_format 7 .
856 .It Cm n
857 Find the Nth next reference which matches the current search pattern
858 (default: 1).
859 .It Cm N
860 Find the Nth previous reference which matches the current search pattern
861 (default: 1).
862 .It Cm Ctrl+l
863 Reload the list of references displayed by the
864 .Cm ref
865 view.
866 .El
867 .Pp
868 The options for
869 .Cm tog ref
870 are as follows:
871 .Bl -tag -width Ds
872 .It Fl r Ar repository-path
873 Use the repository at the specified path.
874 If not specified, assume the repository is located at or above the current
875 working directory.
876 If this directory is a
877 .Xr got 1
878 work tree, use the repository path associated with this work tree.
879 .El
880 .El
881 .Sh ENVIRONMENT
882 .Bl -tag -width TOG_VIEW_SPLIT_MODE
883 .It Ev TOG_COLORS
884 .Nm
885 shows colorized output if this variable is set to a non-empty value.
886 The default color scheme can be modified by setting the environment
887 variables documented below.
888 The colors available in color schemes are
889 .Dq black ,
890 .Dq red ,
891 .Dq green ,
892 .Dq yellow ,
893 .Dq blue ,
894 .Dq magenta ,
895 .Dq cyan ,
896 and
897 .Dq default
898 which maps to the terminal's default foreground color.
899 .It Ev TOG_COLOR_AUTHOR
900 The color used to mark up author information.
901 If not set, the default value
902 .Dq cyan
903 is used.
904 .It Ev TOG_COLOR_COMMIT
905 The color used to mark up commit IDs.
906 If not set, the default value
907 .Dq green
908 is used.
909 .It Ev TOG_COLOR_DATE
910 The color used to mark up date information.
911 If not set, the default value
912 .Dq yellow
913 is used.
914 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
915 The color used to mark up chunk header lines in diffs.
916 If not set, the default value
917 .Dq yellow
918 is used.
919 .It Ev TOG_COLOR_DIFF_META
920 The color used to mark up meta data in diffs.
921 If not set, the default value
922 .Dq green
923 is used.
924 .It Ev TOG_COLOR_DIFF_MINUS
925 The color used to mark up removed lines in diffs.
926 If not set, the default value
927 .Dq magenta
928 is used.
929 .It Ev TOG_COLOR_DIFF_PLUS
930 The color used to mark up added lines in diffs.
931 If not set, the default value
932 .Dq cyan
933 is used.
934 .It Ev TOG_COLOR_REFS_BACKUP
935 The color used to mark up references in the
936 .Dq refs/got/backup/
937 namespace.
938 If not set, the default value
939 .Dq cyan
940 is used.
941 .It Ev TOG_COLOR_REFS_HEADS
942 The color used to mark up references in the
943 .Dq refs/heads/
944 namespace.
945 If not set, the default value
946 .Dq green
947 is used.
948 .It Ev TOG_COLOR_REFS_REMOTES
949 The color used to mark up references in the
950 .Dq refs/remotes/
951 namespace.
952 If not set, the default value
953 .Dq yellow
954 is used.
955 .It Ev TOG_COLOR_REFS_TAGS
956 The color used to mark up references in the
957 .Dq refs/tags/
958 namespace.
959 If not set, the default value
960 .Dq magenta
961 is used.
962 .It Ev TOG_COLOR_TREE_DIRECTORY
963 The color used to mark up directory tree entries.
964 If not set, the default value
965 .Dq cyan
966 is used.
967 .It Ev TOG_COLOR_TREE_EXECUTABLE
968 The color used to mark up executable file tree entries.
969 If not set, the default value
970 .Dq green
971 is used.
972 .It Ev TOG_COLOR_TREE_SUBMODULE
973 The color used to mark up submodule tree entries.
974 If not set, the default value
975 .Dq magenta
976 is used.
977 .It Ev TOG_COLOR_TREE_SYMLINK
978 The color used to mark up symbolic link tree entries.
979 If not set, the default value
980 .Dq magenta
981 is used.
982 .It Ev TOG_DIFF_ALGORITHM
983 Determines the default diff algorithm used by
984 .Nm .
985 Supported diff algorithms are Myers (quick and dirty) and
986 Patience (slow and tidy).
987 Valid values for
988 .Ev TOG_DIFF_ALGORITHM
989 are
990 .Dq patience
991 and
992 .Dq myers .
993 If unset, the Patience diff algorithm will be used by default.
994 .It Ev TOG_VIEW_SPLIT_MODE
995 Determines the default layout of split-screen views.
996 If set to
997 .Dq h
998 or
999 .Dq H ,
1000 .Nm
1001 will use horizontal split by default.
1002 Otherwise, vertical split will be used.
1003 The
1004 .Cm S
1005 key can be used to switch between vertical and horizontal split layout
1006 at run-time.
1007 .El
1008 .Sh EXIT STATUS
1009 .Ex -std tog
1010 .Sh SEE ALSO
1011 .Xr got 1 ,
1012 .Xr git-repository 5 ,
1013 .Xr re_format 7
1014 .Sh AUTHORS
1015 .An Christian Weisgerber Aq Mt naddy@openbsd.org
1016 .An Josh Rickmar Aq Mt jrick@zettaport.com
1017 .An Joshua Stein Aq Mt jcs@openbsd.org
1018 .An Mark Jamsek Aq Mt mark@jamsek.dev
1019 .An Martin Pieuchot Aq Mt mpi@openbsd.org
1020 .An Omar Polo Aq Mt op@openbsd.org
1021 .An Stefan Sperling Aq Mt stsp@openbsd.org
1022 .An Klemens Nanni Aq Mt kn@openbsd.org