2 .\" Copyright (c) 2018 Stefan Sperling
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.
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.
21 .Nd Git repository browser
32 is an interactive read-only browser for Git repositories.
33 This repository format is described in
34 .Xr git-repository 5 .
37 supports several types of views which display repository data:
40 Displays commits in the repository's history.
41 This view is displayed initially if no
43 is specified, or if just a
47 Displays changes made in a particular commit.
49 Displays the line-by-line history of a file.
51 Displays the tree corresponding to a particular commit.
53 Displays references in the repository.
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.
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
70 Global options must precede the command name, and are as follows:
71 .Bl -tag -width tenletters
73 Display usage information.
75 Display program version and exit immediately.
78 The global key bindings are:
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
91 Quit the view which is in focus.
93 Switch focus between views.
95 Toggle fullscreen mode for a split-screen view.
97 will automatically use vertical split-screen views if the size of the
98 terminal window is sufficiently large.
100 Switch the current split-screen layout, and render all active views in
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.
106 When in a split-screen view, decrease the size of the focussed split
107 N increments (default: 1).
109 When in a split-screen view, increase the size of the focussed split
110 N increments (default: 1).
112 Go to line N in the view (default: last line).
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).
118 Output moves left on the screen.
120 Scroll view to the left N increments (default: 1).
122 Output moves right on the screen.
124 Scroll view to the rightmost position.
126 Scroll view left to the start of the line.
132 .Bl -tag -width blame
137 .Op Fl r Ar repository-path
140 Display history of a repository.
143 is specified, show only commits which modified this path.
144 If invoked in a work tree, the
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.
150 This command is also executed if no explicit command is specified.
154 are as follows (N denotes optional prefixed count modifier):
156 .It Cm Down-arrow, j, >, Full stop, Ctrl-n
157 Move the selection cursor down N lines (default: 1).
158 .It Cm Up-arrow, k, <, Comma, Ctrl-p
159 Move the selection cursor up N lines (default: 1).
160 .It Cm Page-down, Space, Ctrl+f, f
161 Move the selection cursor down N pages (default: 1).
162 .It Cm Page-up, Ctrl+b, b
163 Move the selection cursor up N pages (default: 1).
165 Move the selection cursor down N half pages (default: 1).
167 Move the selection cursor up N half pages (default: 1).
169 Move the cursor to the newest commit.
171 Move the cursor to the oldest commit.
172 This will traverse all commits on the current branch which may take
173 a long time depending on the number of commits in branch history.
174 If needed, this operation can be cancelled with
179 Move the cursor to commit N (default: 1).
183 but defaults to the oldest commit.
187 view showing file changes made in the currently selected commit.
191 view showing the tree for the currently selected commit.
193 Show log entries for the parent directory of the currently selected path.
194 However when an active search is in progress or when additional commits
197 aborts the running operation.
199 Prompt for a search pattern and start searching for matching commits.
200 The search pattern is an extended regular expression which is matched
201 against a commit's author name, committer name, log message, and
203 Regular expression syntax is documented in
206 Prompt for a pattern and limit the log view's list of commits to those
207 which match the pattern.
208 If no pattern is specified, i.e. the
210 prompt is immediately closed with the Enter key, then the pattern is
212 Until the pattern is cleared, the limited list of commits replaces the
213 full list of commits for all operations supported by the log view.
214 For example, a search started with
216 will search the limited list of commits, rather than searching all commits.
217 The pattern is an extended regular expression which is matched
218 against a commit's author name, committer name, log message, and
220 Regular expression syntax is documented in
223 Find the Nth next commit which matches the current search pattern (default: 1).
225 Searching continues until either a match is found or
231 Find the Nth previous commit which matches the current search pattern
234 Searching continues until either a match is found or
242 view with new commits found in the repository.
246 view and toggle display of merged commits.
249 option determines whether merged commits are displayed initially.
253 view listing all references in the repository.
254 This can then be used to open a new
256 view for arbitrary branches and tags.
258 Toggle between showing the committer name and the author name.
266 Display individual commits which were merged into the current branch
270 shows the linear history of the current branch only.
273 key binding can be used to toggle display of merged commits at run-time.
275 Start traversing history at the specified
277 The expected argument is a commit ID SHA1 hash, or a reference name or keyword
278 which will be resolved to a commit ID.
279 An abbreviated hash argument will be expanded to a full SHA1 hash
280 automatically, provided the abbreviation is unique.
285 resolve to the work tree's base commit and branch head, respectively.
286 The former is only valid if invoked in a work tree, while the latter will
287 resolve to the tip of the work tree's current branch if invoked in a
288 work tree, otherwise it will resolve to the repository's HEAD reference.
289 Keywords and references may be appended with
293 modifiers and an optional integer N to denote the
294 Nth descendant or antecedent by first parent traversal, respectively;
297 denotes the work tree branch head's 2nd generation ancestor, and
299 denotes the 4th generation descendant of the work tree's base commit.
302 will denote the 3rd generation descendant of the commit resolved by the
309 modifier without a trailing integer has an implicit
317 .It Fl r Ar repository-path
318 Use the repository at the specified path.
319 If not specified, assume the repository is located at or above the current
321 If this directory is a
323 work tree, use the repository path associated with this work tree.
329 .Op Fl r Ar repository-path
333 Display the differences between two objects in the repository.
334 Treat each of the two arguments as a reference, a tag name, an object
335 ID SHA1 hash, or a keyword and display differences between the corresponding
337 Both objects must be of the same type (blobs, trees, or commits).
338 An abbreviated hash argument will be expanded to a full SHA1 hash
339 automatically, provided the abbreviation is unique.
344 resolve to the work tree's base commit and branch head, respectively.
345 The former is only valid if invoked in a work tree, while the latter will
346 resolve to the tip of the work tree's current branch if invoked in a
347 work tree, otherwise it will resolve to the repository's HEAD reference.
348 Keywords and references may be appended with
352 modifiers and an optional integer N to denote the
353 Nth descendant or antecedent by first parent traversal, respectively;
356 denotes the work tree branch head's 2nd generation ancestor, and
358 denotes the 4th generation descendant of the work tree's base commit.
361 will denote the 3rd generation descendant of the commit resolved by the
368 modifier without a trailing integer has an implicit
379 are as follows (N denotes optional prefixed count modifier):
382 Toggle treatment of file contents as ASCII text even if binary data was
384 .It Cm Down-arrow, j, Ctrl-n
385 Scroll down N lines (default: 1).
386 .It Cm Up-arrow, k, Ctrl-p
387 Scroll up N lines (default: 1).
388 .It Cm Page-down, Space, Ctrl+f, f
389 Scroll down N pages (default: 1).
390 .It Cm Page-up, Ctrl+b, b
391 Scroll up N pages (default: 1).
393 Scroll down N half pages (default: 1).
395 Scroll up N half pages (default: 1).
397 Scroll to the top of the view.
399 Scroll to the bottom of the view.
401 Scroll to line N (default: 1).
405 but defaults to the last line in the diff.
407 Navigate to the Nth previous file in the diff (default: 1).
409 Navigate to the Nth next file in the diff (default: 1).
411 Navigate to the Nth previous hunk in the diff (default: 1).
413 Navigate to the Nth next hunk in the diff (default: 1).
415 Reduce diff context by N lines (default: 1).
417 Increase diff context by N lines (default: 1).
421 view was opened via the
423 view, move to the Nth previous (younger) commit.
424 If the diff was opened via the
426 view, move to the Nth previous line and load the corresponding commit
428 .It Cm >, Full stop, J
431 view was opened via the
433 view, move to the Nth next (older) commit.
434 If the diff was opened via the
436 view, move to the Nth next line and load the corresponding commit (default: 1).
438 Prompt for a search pattern and start searching for matching lines.
439 The search pattern is an extended regular expression.
440 Regular expression syntax is documented in
443 Find the Nth next line which matches the current search pattern (default: 1).
445 Find the Nth previous line which matches the current search pattern
448 Toggle display of whitespace-only changes.
450 Change the diff algorithm.
451 Supported diff algorithms are Myers (quick and dirty) and
452 Patience (slow and tidy).
453 This is a global setting which also affects the
463 Treat file contents as ASCII text even if binary data is detected.
465 Set the number of context lines shown in the diff.
466 By default, 3 lines of context are shown.
467 .It Fl r Ar repository-path
468 Use the repository at the specified path.
469 If not specified, assume the repository is located at or above the current
471 If this directory is a
473 work tree, use the repository path associated with this work tree.
475 Ignore whitespace-only changes.
480 .Op Fl r Ar repository-path
483 Display line-by-line history of a file at the specified path.
487 are as follows (N denotes optional prefixed count modifier):
489 .It Cm Down-arrow, j, Ctrl-n
490 Move the selection cursor down N pages (default: 1).
491 .It Cm Up-arrow, k, Ctrl-p
492 Move the selection cursor up N pages (default: 1).
493 .It Cm Page-down, Space, Ctrl+f, f
494 Move the selection cursor down N pages (default: 1).
495 .It Cm Page-up, Ctrl+b, b
496 Move the selection cursor up N pages (default: 1).
498 Move the selection cursor down N half pages (default: 1).
500 Move the selection cursor up N half pages (default: 1).
502 Move the selection cursor to the first line of the file.
504 Move the selection cursor to the last line of the file.
506 Move the selection cursor to line N (default: 1).
510 but defaults to the last line in the file.
514 view for the currently selected line's commit.
518 view with the version of the file as found in the currently
519 selected line's commit.
523 view with the version of the file as found in the parent commit of the
524 currently selected line's commit.
528 view with the previously blamed commit.
532 view for the currently selected annotated line.
534 Prompt for a search pattern and start searching for matching lines.
535 The search pattern is an extended regular expression.
536 Regular expression syntax is documented in
539 Find the Nth next line which matches the current search pattern (default: 1).
541 Find the Nth previous line which matches the current search pattern
544 Change the diff algorithm.
545 Supported diff algorithms are Myers (quick and dirty) and
546 Patience (slow and tidy).
547 This is a global setting which also affects the
557 Start traversing history at the specified
559 The expected argument is a commit ID SHA1 hash, or a reference name or keyword
560 which will be resolved to a commit ID.
561 An abbreviated hash argument will be expanded to a full SHA1 hash
562 automatically, provided the abbreviation is unique.
567 resolve to the work tree's base commit and branch head, respectively.
568 The former is only valid if invoked in a work tree, while the latter will
569 resolve to the tip of the work tree's current branch if invoked in a
570 work tree, otherwise it will resolve to the repository's HEAD reference.
571 Keywords and references may be appended with
575 modifiers and an optional integer N to denote the
576 Nth descendant or antecedent by first parent traversal, respectively;
579 denotes the work tree branch head's 2nd generation ancestor, and
581 denotes the 4th generation descendant of the work tree's base commit.
584 will denote the 3rd generation descendant of the commit resolved by the
591 modifier without a trailing integer has an implicit
599 .It Fl r Ar repository-path
600 Use the repository at the specified path.
601 If not specified, assume the repository is located at or above the current
603 If this directory is a
605 work tree, use the repository path associated with this work tree.
610 .Op Fl r Ar repository-path
613 Display the repository tree.
616 is specified, show tree entries at this path.
618 Displayed tree entries may carry one of the following trailing annotations:
619 .Bl -column YXZ description
620 .It @ Ta entry is a symbolic link
621 .It / Ta entry is a directory
622 .It * Ta entry is an executable file
623 .It $ Ta entry is a Git submodule
626 Symbolic link entries are also annotated with the target path of the link.
630 are as follows (N denotes optional prefixed count modifier):
632 .It Cm Down-arrow, j, Ctrl-n
633 Move the selection cursor down N lines (default: 1).
634 .It Cm Up-arrow, k, Ctrl-p
635 Move the selection cursor up N lines (default: 1).
636 .It Cm Page-down, Space, Ctrl+f, f
637 Move the selection cursor down N pages (default: 1).
638 .It Cm Page-up, Ctrl+b, b
639 Move the selection cursor up N pages (default: 1).
641 Move the selection cursor down N half pages (default: 1).
643 Move the selection cursor up N half pages (default: 1).
645 Move the selection cursor to the first entry.
647 Move the selection cursor to the last entry.
649 Move the selection cursor to entry N (default: 1).
653 but defaults to the last entry.
655 Enter the currently selected directory, or switch to the
657 view for the currently selected file.
661 view for the currently selected tree entry.
665 view listing all references in the repository.
666 This can then be used to open a new
668 view for arbitrary branches and tags.
670 Move back to the Nth parent directory (default: 1).
672 Show object IDs for all objects displayed in the
676 Prompt for a search pattern and start searching for matching tree entries.
677 The search pattern is an extended regular expression which is matched
678 against the tree entry's name.
679 Regular expression syntax is documented in
682 Find the Nth next tree entry which matches the current search pattern
685 Find the Nth previous tree entry which matches the current search pattern
694 Start traversing history at the specified
696 The expected argument is a commit ID SHA1 hash, or a reference name or keyword
697 which will be resolved to a commit ID.
698 An abbreviated hash argument will be expanded to a full SHA1 hash
699 automatically, provided the abbreviation is unique.
704 resolve to the work tree's base commit and branch head, respectively.
705 The former is only valid if invoked in a work tree, while the latter will
706 resolve to the tip of the work tree's current branch if invoked in a
707 work tree, otherwise it will resolve to the repository's HEAD reference.
708 Keywords and references may be appended with
712 modifiers and an optional integer N to denote the
713 Nth descendant or antecedent by first parent traversal, respectively;
716 denotes the work tree branch head's 2nd generation ancestor, and
718 denotes the 4th generation descendant of the work tree's base commit.
721 will denote the 3rd generation descendant of the commit resolved by the
728 modifier without a trailing integer has an implicit
736 .It Fl r Ar repository-path
737 Use the repository at the specified path.
738 If not specified, assume the repository is located at or above the current
740 If this directory is a
742 work tree, use the repository path associated with this work tree.
744 .It Cm ref Op Fl r Ar repository-path
745 Display references in the repository.
749 are as follows (N denotes optional prefixed count modifier):
751 .It Cm Down-arrow, j, Ctrl-n
752 Move the selection cursor down N lines (default: 1).
753 .It Cm Up-arrow, k, Ctrl-p
754 Move the selection cursor up N lines (default: 1).
755 .It Cm Page-down, Space, Ctrl+f, f
756 Move the selection cursor down N pages (default: 1).
757 .It Cm Page-up, Ctrl+b, b
758 Move the selection cursor up N pages (default: 1).
760 Move the selection cursor down N half pages (default: 1).
762 Move the selection cursor up N half pages (default: 1).
764 Move the selection cursor to the first reference.
766 Move the selection cursor to the last reference.
768 Move the selection cursor to reference N (default: 1).
772 but defaults to the last reference.
776 view which begins traversing history at the commit resolved via the
777 currently selected reference.
781 view showing the tree resolved via the currently selected reference.
783 Show object IDs for all non-symbolic references displayed in the
787 Show last modified date of each displayed reference.
789 Toggle display order of references between sort by name and sort by timestamp.
791 Prompt for a search pattern and start searching for matching references.
792 The search pattern is an extended regular expression which is matched
793 against absolute reference names.
794 Regular expression syntax is documented in
797 Find the Nth next reference which matches the current search pattern
800 Find the Nth previous reference which matches the current search pattern
803 Reload the list of references displayed by the
812 .It Fl r Ar repository-path
813 Use the repository at the specified path.
814 If not specified, assume the repository is located at or above the current
816 If this directory is a
818 work tree, use the repository path associated with this work tree.
822 .Bl -tag -width TOG_VIEW_SPLIT_MODE
825 shows colorized output if this variable is set to a non-empty value.
826 The default color scheme can be modified by setting the environment
827 variables documented below.
828 The colors available in color schemes are
838 which maps to the terminal's default foreground color.
839 .It Ev TOG_COLOR_AUTHOR
840 The color used to mark up author information.
841 If not set, the default value
844 .It Ev TOG_COLOR_COMMIT
845 The color used to mark up commit IDs.
846 If not set, the default value
849 .It Ev TOG_COLOR_DATE
850 The color used to mark up date information.
851 If not set, the default value
854 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
855 The color used to mark up chunk header lines in diffs.
856 If not set, the default value
859 .It Ev TOG_COLOR_DIFF_META
860 The color used to mark up meta data in diffs.
861 If not set, the default value
864 .It Ev TOG_COLOR_DIFF_MINUS
865 The color used to mark up removed lines in diffs.
866 If not set, the default value
869 .It Ev TOG_COLOR_DIFF_PLUS
870 The color used to mark up added lines in diffs.
871 If not set, the default value
874 .It Ev TOG_COLOR_REFS_BACKUP
875 The color used to mark up references in the
878 If not set, the default value
881 .It Ev TOG_COLOR_REFS_HEADS
882 The color used to mark up references in the
885 If not set, the default value
888 .It Ev TOG_COLOR_REFS_REMOTES
889 The color used to mark up references in the
892 If not set, the default value
895 .It Ev TOG_COLOR_REFS_TAGS
896 The color used to mark up references in the
899 If not set, the default value
902 .It Ev TOG_COLOR_TREE_DIRECTORY
903 The color used to mark up directory tree entries.
904 If not set, the default value
907 .It Ev TOG_COLOR_TREE_EXECUTABLE
908 The color used to mark up executable file tree entries.
909 If not set, the default value
912 .It Ev TOG_COLOR_TREE_SUBMODULE
913 The color used to mark up submodule tree entries.
914 If not set, the default value
917 .It Ev TOG_COLOR_TREE_SYMLINK
918 The color used to mark up symbolic link tree entries.
919 If not set, the default value
922 .It Ev TOG_DIFF_ALGORITHM
923 Determines the default diff algorithm used by
925 Supported diff algorithms are Myers (quick and dirty) and
926 Patience (slow and tidy).
928 .Ev TOG_DIFF_ALGORITHM
933 If unset, the Myers diff algorithm will be used by default.
934 .It Ev TOG_VIEW_SPLIT_MODE
935 Determines the default layout of split-screen views.
941 will use horizontal split by default.
942 Otherwise, vertical split will be used.
945 key can be used to switch between vertical and horizontal split layout
952 .Xr git-repository 5 ,
955 .An Christian Weisgerber Aq Mt naddy@openbsd.org
956 .An Josh Rickmar Aq Mt jrick@zettaport.com
957 .An Joshua Stein Aq Mt jcs@openbsd.org
958 .An Mark Jamsek Aq Mt mark@jamsek.dev
959 .An Martin Pieuchot Aq Mt mpi@openbsd.org
960 .An Omar Polo Aq Mt op@openbsd.org
961 .An Stefan Sperling Aq Mt stsp@openbsd.org
962 .An Klemens Nanni Aq Mt kn@openbsd.org
