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 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
158 This command is also executed if no explicit command is specified.
162 are as follows (N denotes optional prefixed count modifier):
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).
173 Move the selection cursor down N half pages (default: 1).
175 Move the selection cursor up N half pages (default: 1).
177 Move the cursor to the newest commit.
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
187 Move the cursor to commit N (default: 1).
191 but defaults to the oldest commit.
195 view showing file changes made in the currently selected commit.
196 If a commit is marked with the
198 key map, open a diff view showing file changes made between the marked commit
199 and the currently selected commit.
201 Mark or unmark the selected commit.
202 When a commit is marked,
205 key on another selected commit opens a
207 view showing the changes between the marked commit and the
208 currently selected commit.
212 view showing the tree for the currently selected commit.
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
218 aborts the running operation.
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
224 Regular expression syntax is documented in
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
231 prompt is immediately closed with the Enter key, then the pattern is
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
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
241 Regular expression syntax is documented in
244 Find the Nth next commit which matches the current search pattern (default: 1).
246 Searching continues until either a match is found or
252 Find the Nth previous commit which matches the current search pattern
255 Searching continues until either a match is found or
263 view with new commits found in the repository.
267 view and toggle display of merged commits.
270 option determines whether merged commits are displayed initially.
274 view listing all references in the repository.
275 This can then be used to open a new
277 view for arbitrary branches and tags.
279 Toggle between showing the committer name and the author name.
287 Display individual commits which were merged into the current branch
291 shows the linear history of the current branch only.
294 key binding can be used to toggle display of merged commits at run-time.
296 Start traversing history at the specified
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.
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
314 modifiers and an optional integer N to denote the
315 Nth descendant or antecedent by first parent traversal, respectively;
318 denotes the work tree branch head's 2nd generation ancestor, and
320 denotes the 4th generation descendant of the work tree's base commit.
323 will denote the 3rd generation descendant of the commit resolved by the
330 modifier without a trailing integer has an implicit
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
342 If this directory is a
344 work tree, use the repository path associated with this work tree.
350 .Op Fl r Ar repository-path
354 Display the differences between two objects in the repository.
355 Treat each of the two arguments as a reference, a tag name, an object
356 ID, or a keyword and display differences between the corresponding
358 Both objects must be of the same type (blobs, trees, or commits).
359 An abbreviated hash argument will be expanded to a full commit ID
360 automatically, provided the abbreviation is unique.
365 resolve to the work tree's base commit and branch head, respectively.
366 The former is only valid if invoked in a work tree, while the latter will
367 resolve to the tip of the work tree's current branch if invoked in a
368 work tree, otherwise it will resolve to the repository's HEAD reference.
369 Keywords and references may be appended with
373 modifiers and an optional integer N to denote the
374 Nth descendant or antecedent by first parent traversal, respectively;
377 denotes the work tree branch head's 2nd generation ancestor, and
379 denotes the 4th generation descendant of the work tree's base commit.
382 will denote the 3rd generation descendant of the commit resolved by the
389 modifier without a trailing integer has an implicit
400 are as follows (N denotes optional prefixed count modifier):
403 Toggle treatment of file contents as ASCII text even if binary data was
405 .It Cm Down-arrow, j, Ctrl-n
406 Scroll down N lines (default: 1).
407 .It Cm Up-arrow, k, Ctrl-p
408 Scroll up N lines (default: 1).
409 .It Cm Page-down, Space, Ctrl+f, f
410 Scroll down N pages (default: 1).
411 .It Cm Page-up, Ctrl+b, b
412 Scroll up N pages (default: 1).
414 Scroll down N half pages (default: 1).
416 Scroll up N half pages (default: 1).
418 Scroll to the top of the view.
420 Scroll to the bottom of the view.
422 Scroll to line N (default: 1).
426 but defaults to the last line in the diff.
428 Navigate to the Nth previous file in the diff (default: 1).
430 Navigate to the Nth next file in the diff (default: 1).
432 Navigate to the Nth previous hunk in the diff (default: 1).
434 Navigate to the Nth next hunk in the diff (default: 1).
436 Reduce diff context by N lines (default: 1).
438 Increase diff context by N lines (default: 1).
442 view was opened via the
444 view, move to the Nth previous (younger) commit.
445 If the diff was opened via the
447 view, move to the Nth previous line and load the corresponding commit
449 .It Cm >, Full stop, J
452 view was opened via the
454 view, move to the Nth next (older) commit.
455 If the diff was opened via the
457 view, move to the Nth next line and load the corresponding commit (default: 1).
459 Write the currently viewed diff to a patch file in
461 The patch pathname is drawn to the status line.
463 Prompt for a search pattern and start searching for matching lines.
464 The search pattern is an extended regular expression.
465 Regular expression syntax is documented in
468 Find the Nth next line which matches the current search pattern (default: 1).
470 Find the Nth previous line which matches the current search pattern
473 Toggle display of whitespace-only changes.
475 Change the diff algorithm.
476 Supported diff algorithms are Myers (quick and dirty) and
477 Patience (slow and tidy).
478 This is a global setting which also affects the
488 Treat file contents as ASCII text even if binary data is detected.
490 Set the number of context lines shown in the diff.
491 By default, 3 lines of context are shown.
492 .It Fl r Ar repository-path
493 Use the repository at the specified path.
494 If not specified, assume the repository is located at or above the current
496 If this directory is a
498 work tree, use the repository path associated with this work tree.
500 Ignore whitespace-only changes.
505 .Op Fl r Ar repository-path
508 Display line-by-line history of a file at the specified path.
512 are as follows (N denotes optional prefixed count modifier):
514 .It Cm Down-arrow, j, Ctrl-n
515 Move the selection cursor down N pages (default: 1).
516 .It Cm Up-arrow, k, Ctrl-p
517 Move the selection cursor up N pages (default: 1).
518 .It Cm Page-down, Space, Ctrl+f, f
519 Move the selection cursor down N pages (default: 1).
520 .It Cm Page-up, Ctrl+b, b
521 Move the selection cursor up N pages (default: 1).
523 Move the selection cursor down N half pages (default: 1).
525 Move the selection cursor up N half pages (default: 1).
527 Move the selection cursor to the first line of the file.
529 Move the selection cursor to the last line of the file.
531 Move the selection cursor to line N (default: 1).
535 but defaults to the last line in the file.
539 view for the currently selected line's commit.
543 view with the version of the file as found in the currently
544 selected line's commit.
548 view with the version of the file as found in the parent commit of the
549 currently selected line's commit.
553 view with the previously blamed commit.
557 view for the currently selected annotated line.
559 Prompt for a search pattern and start searching for matching lines.
560 The search pattern is an extended regular expression.
561 Regular expression syntax is documented in
564 Find the Nth next line which matches the current search pattern (default: 1).
566 Find the Nth previous line which matches the current search pattern
569 Change the diff algorithm.
570 Supported diff algorithms are Myers (quick and dirty) and
571 Patience (slow and tidy).
572 This is a global setting which also affects the
582 Start traversing history at the specified
584 The expected argument is a commit ID, or a reference name or keyword
585 which will be resolved to a commit ID.
586 An abbreviated hash argument will be expanded to a full commit ID
587 automatically, provided the abbreviation is unique.
592 resolve to the work tree's base commit and branch head, respectively.
593 The former is only valid if invoked in a work tree, while the latter will
594 resolve to the tip of the work tree's current branch if invoked in a
595 work tree, otherwise it will resolve to the repository's HEAD reference.
596 Keywords and references may be appended with
600 modifiers and an optional integer N to denote the
601 Nth descendant or antecedent by first parent traversal, respectively;
604 denotes the work tree branch head's 2nd generation ancestor, and
606 denotes the 4th generation descendant of the work tree's base commit.
609 will denote the 3rd generation descendant of the commit resolved by the
616 modifier without a trailing integer has an implicit
624 .It Fl r Ar repository-path
625 Use the repository at the specified path.
626 If not specified, assume the repository is located at or above the current
628 If this directory is a
630 work tree, use the repository path associated with this work tree.
635 .Op Fl r Ar repository-path
638 Display the repository tree.
641 is specified, show tree entries at this path.
643 Displayed tree entries may carry one of the following trailing annotations:
644 .Bl -column YXZ description
645 .It @ Ta entry is a symbolic link
646 .It / Ta entry is a directory
647 .It * Ta entry is an executable file
648 .It $ Ta entry is a Git submodule
651 Symbolic link entries are also annotated with the target path of the link.
655 are as follows (N denotes optional prefixed count modifier):
657 .It Cm Down-arrow, j, Ctrl-n
658 Move the selection cursor down N lines (default: 1).
659 .It Cm Up-arrow, k, Ctrl-p
660 Move the selection cursor up N lines (default: 1).
661 .It Cm Page-down, Space, Ctrl+f, f
662 Move the selection cursor down N pages (default: 1).
663 .It Cm Page-up, Ctrl+b, b
664 Move the selection cursor up N pages (default: 1).
666 Move the selection cursor down N half pages (default: 1).
668 Move the selection cursor up N half pages (default: 1).
670 Move the selection cursor to the first entry.
672 Move the selection cursor to the last entry.
674 Move the selection cursor to entry N (default: 1).
678 but defaults to the last entry.
680 Enter the currently selected directory, or switch to the
682 view for the currently selected file.
686 view for the currently selected tree entry.
690 view listing all references in the repository.
691 This can then be used to open a new
693 view for arbitrary branches and tags.
695 Move back to the Nth parent directory (default: 1).
697 Show object IDs for all objects displayed in the
701 Prompt for a search pattern and start searching for matching tree entries.
702 The search pattern is an extended regular expression which is matched
703 against the tree entry's name.
704 Regular expression syntax is documented in
707 Find the Nth next tree entry which matches the current search pattern
710 Find the Nth previous tree entry which matches the current search pattern
719 Start traversing history at the specified
721 The expected argument is a commit ID, or a reference name or keyword
722 which will be resolved to a commit ID.
723 An abbreviated hash argument will be expanded to a full commit ID
724 automatically, provided the abbreviation is unique.
729 resolve to the work tree's base commit and branch head, respectively.
730 The former is only valid if invoked in a work tree, while the latter will
731 resolve to the tip of the work tree's current branch if invoked in a
732 work tree, otherwise it will resolve to the repository's HEAD reference.
733 Keywords and references may be appended with
737 modifiers and an optional integer N to denote the
738 Nth descendant or antecedent by first parent traversal, respectively;
741 denotes the work tree branch head's 2nd generation ancestor, and
743 denotes the 4th generation descendant of the work tree's base commit.
746 will denote the 3rd generation descendant of the commit resolved by the
753 modifier without a trailing integer has an implicit
761 .It Fl r Ar repository-path
762 Use the repository at the specified path.
763 If not specified, assume the repository is located at or above the current
765 If this directory is a
767 work tree, use the repository path associated with this work tree.
769 .It Cm ref Op Fl r Ar repository-path
770 Display references in the repository.
774 are as follows (N denotes optional prefixed count modifier):
776 .It Cm Down-arrow, j, Ctrl-n
777 Move the selection cursor down N lines (default: 1).
778 .It Cm Up-arrow, k, Ctrl-p
779 Move the selection cursor up N lines (default: 1).
780 .It Cm Page-down, Space, Ctrl+f, f
781 Move the selection cursor down N pages (default: 1).
782 .It Cm Page-up, Ctrl+b, b
783 Move the selection cursor up N pages (default: 1).
785 Move the selection cursor down N half pages (default: 1).
787 Move the selection cursor up N half pages (default: 1).
789 Move the selection cursor to the first reference.
791 Move the selection cursor to the last reference.
793 Move the selection cursor to reference N (default: 1).
797 but defaults to the last reference.
801 view which begins traversing history at the commit resolved via the
802 currently selected reference.
806 view showing the tree resolved via the currently selected reference.
808 Show object IDs for all non-symbolic references displayed in the
812 Show last modified date of each displayed reference.
814 Toggle display order of references between sort by name and sort by timestamp.
816 Prompt for a search pattern and start searching for matching references.
817 The search pattern is an extended regular expression which is matched
818 against absolute reference names.
819 Regular expression syntax is documented in
822 Find the Nth next reference which matches the current search pattern
825 Find the Nth previous reference which matches the current search pattern
828 Reload the list of references displayed by the
837 .It Fl r Ar repository-path
838 Use the repository at the specified path.
839 If not specified, assume the repository is located at or above the current
841 If this directory is a
843 work tree, use the repository path associated with this work tree.
847 .Bl -tag -width TOG_VIEW_SPLIT_MODE
850 shows colorized output if this variable is set to a non-empty value.
851 The default color scheme can be modified by setting the environment
852 variables documented below.
853 The colors available in color schemes are
863 which maps to the terminal's default foreground color.
864 .It Ev TOG_COLOR_AUTHOR
865 The color used to mark up author information.
866 If not set, the default value
869 .It Ev TOG_COLOR_COMMIT
870 The color used to mark up commit IDs.
871 If not set, the default value
874 .It Ev TOG_COLOR_DATE
875 The color used to mark up date information.
876 If not set, the default value
879 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
880 The color used to mark up chunk header lines in diffs.
881 If not set, the default value
884 .It Ev TOG_COLOR_DIFF_META
885 The color used to mark up meta data in diffs.
886 If not set, the default value
889 .It Ev TOG_COLOR_DIFF_MINUS
890 The color used to mark up removed lines in diffs.
891 If not set, the default value
894 .It Ev TOG_COLOR_DIFF_PLUS
895 The color used to mark up added lines in diffs.
896 If not set, the default value
899 .It Ev TOG_COLOR_REFS_BACKUP
900 The color used to mark up references in the
903 If not set, the default value
906 .It Ev TOG_COLOR_REFS_HEADS
907 The color used to mark up references in the
910 If not set, the default value
913 .It Ev TOG_COLOR_REFS_REMOTES
914 The color used to mark up references in the
917 If not set, the default value
920 .It Ev TOG_COLOR_REFS_TAGS
921 The color used to mark up references in the
924 If not set, the default value
927 .It Ev TOG_COLOR_TREE_DIRECTORY
928 The color used to mark up directory tree entries.
929 If not set, the default value
932 .It Ev TOG_COLOR_TREE_EXECUTABLE
933 The color used to mark up executable file tree entries.
934 If not set, the default value
937 .It Ev TOG_COLOR_TREE_SUBMODULE
938 The color used to mark up submodule tree entries.
939 If not set, the default value
942 .It Ev TOG_COLOR_TREE_SYMLINK
943 The color used to mark up symbolic link tree entries.
944 If not set, the default value
947 .It Ev TOG_DIFF_ALGORITHM
948 Determines the default diff algorithm used by
950 Supported diff algorithms are Myers (quick and dirty) and
951 Patience (slow and tidy).
953 .Ev TOG_DIFF_ALGORITHM
958 If unset, the Patience diff algorithm will be used by default.
959 .It Ev TOG_VIEW_SPLIT_MODE
960 Determines the default layout of split-screen views.
966 will use horizontal split by default.
967 Otherwise, vertical split will be used.
970 key can be used to switch between vertical and horizontal split layout
977 .Xr git-repository 5 ,
980 .An Christian Weisgerber Aq Mt naddy@openbsd.org
981 .An Josh Rickmar Aq Mt jrick@zettaport.com
982 .An Joshua Stein Aq Mt jcs@openbsd.org
983 .An Mark Jamsek Aq Mt mark@jamsek.dev
984 .An Martin Pieuchot Aq Mt mpi@openbsd.org
985 .An Omar Polo Aq Mt op@openbsd.org
986 .An Stefan Sperling Aq Mt stsp@openbsd.org
987 .An Klemens Nanni Aq Mt kn@openbsd.org
