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.
199 view showing the tree for the currently selected commit.
201 Show log entries for the parent directory of the currently selected path.
202 However when an active search is in progress or when additional commits
205 aborts the running operation.
207 Prompt for a search pattern and start searching for matching commits.
208 The search pattern is an extended regular expression which is matched
209 against a commit's author name, committer name, log message, and
211 Regular expression syntax is documented in
214 Prompt for a pattern and limit the log view's list of commits to those
215 which match the pattern.
216 If no pattern is specified, i.e. the
218 prompt is immediately closed with the Enter key, then the pattern is
220 Until the pattern is cleared, the limited list of commits replaces the
221 full list of commits for all operations supported by the log view.
222 For example, a search started with
224 will search the limited list of commits, rather than searching all commits.
225 The pattern is an extended regular expression which is matched
226 against a commit's author name, committer name, log message, and
228 Regular expression syntax is documented in
231 Find the Nth next commit which matches the current search pattern (default: 1).
233 Searching continues until either a match is found or
239 Find the Nth previous commit which matches the current search pattern
242 Searching continues until either a match is found or
250 view with new commits found in the repository.
254 view and toggle display of merged commits.
257 option determines whether merged commits are displayed initially.
261 view listing all references in the repository.
262 This can then be used to open a new
264 view for arbitrary branches and tags.
266 Toggle between showing the committer name and the author name.
274 Display individual commits which were merged into the current branch
278 shows the linear history of the current branch only.
281 key binding can be used to toggle display of merged commits at run-time.
283 Start traversing history at the specified
285 The expected argument is a commit ID SHA1 hash, or a reference name or keyword
286 which will be resolved to a commit ID.
287 An abbreviated hash argument will be expanded to a full SHA1 hash
288 automatically, provided the abbreviation is unique.
293 resolve to the work tree's base commit and branch head, respectively.
294 The former is only valid if invoked in a work tree, while the latter will
295 resolve to the tip of the work tree's current branch if invoked in a
296 work tree, otherwise it will resolve to the repository's HEAD reference.
297 Keywords and references may be appended with
301 modifiers and an optional integer N to denote the
302 Nth descendant or antecedent by first parent traversal, respectively;
305 denotes the work tree branch head's 2nd generation ancestor, and
307 denotes the 4th generation descendant of the work tree's base commit.
310 will denote the 3rd generation descendant of the commit resolved by the
317 modifier without a trailing integer has an implicit
325 .It Fl r Ar repository-path
326 Use the repository at the specified path.
327 If not specified, assume the repository is located at or above the current
329 If this directory is a
331 work tree, use the repository path associated with this work tree.
337 .Op Fl r Ar repository-path
341 Display the differences between two objects in the repository.
342 Treat each of the two arguments as a reference, a tag name, an object
343 ID SHA1 hash, or a keyword and display differences between the corresponding
345 Both objects must be of the same type (blobs, trees, or commits).
346 An abbreviated hash argument will be expanded to a full SHA1 hash
347 automatically, provided the abbreviation is unique.
352 resolve to the work tree's base commit and branch head, respectively.
353 The former is only valid if invoked in a work tree, while the latter will
354 resolve to the tip of the work tree's current branch if invoked in a
355 work tree, otherwise it will resolve to the repository's HEAD reference.
356 Keywords and references may be appended with
360 modifiers and an optional integer N to denote the
361 Nth descendant or antecedent by first parent traversal, respectively;
364 denotes the work tree branch head's 2nd generation ancestor, and
366 denotes the 4th generation descendant of the work tree's base commit.
369 will denote the 3rd generation descendant of the commit resolved by the
376 modifier without a trailing integer has an implicit
387 are as follows (N denotes optional prefixed count modifier):
390 Toggle treatment of file contents as ASCII text even if binary data was
392 .It Cm Down-arrow, j, Ctrl-n
393 Scroll down N lines (default: 1).
394 .It Cm Up-arrow, k, Ctrl-p
395 Scroll up N lines (default: 1).
396 .It Cm Page-down, Space, Ctrl+f, f
397 Scroll down N pages (default: 1).
398 .It Cm Page-up, Ctrl+b, b
399 Scroll up N pages (default: 1).
401 Scroll down N half pages (default: 1).
403 Scroll up N half pages (default: 1).
405 Scroll to the top of the view.
407 Scroll to the bottom of the view.
409 Scroll to line N (default: 1).
413 but defaults to the last line in the diff.
415 Navigate to the Nth previous file in the diff (default: 1).
417 Navigate to the Nth next file in the diff (default: 1).
419 Navigate to the Nth previous hunk in the diff (default: 1).
421 Navigate to the Nth next hunk in the diff (default: 1).
423 Reduce diff context by N lines (default: 1).
425 Increase diff context by N lines (default: 1).
429 view was opened via the
431 view, move to the Nth previous (younger) commit.
432 If the diff was opened via the
434 view, move to the Nth previous line and load the corresponding commit
436 .It Cm >, Full stop, J
439 view was opened via the
441 view, move to the Nth next (older) commit.
442 If the diff was opened via the
444 view, move to the Nth next line and load the corresponding commit (default: 1).
446 Prompt for a search pattern and start searching for matching lines.
447 The search pattern is an extended regular expression.
448 Regular expression syntax is documented in
451 Find the Nth next line which matches the current search pattern (default: 1).
453 Find the Nth previous line which matches the current search pattern
456 Toggle display of whitespace-only changes.
458 Change the diff algorithm.
459 Supported diff algorithms are Myers (quick and dirty) and
460 Patience (slow and tidy).
461 This is a global setting which also affects the
471 Treat file contents as ASCII text even if binary data is detected.
473 Set the number of context lines shown in the diff.
474 By default, 3 lines of context are shown.
475 .It Fl r Ar repository-path
476 Use the repository at the specified path.
477 If not specified, assume the repository is located at or above the current
479 If this directory is a
481 work tree, use the repository path associated with this work tree.
483 Ignore whitespace-only changes.
488 .Op Fl r Ar repository-path
491 Display line-by-line history of a file at the specified path.
495 are as follows (N denotes optional prefixed count modifier):
497 .It Cm Down-arrow, j, Ctrl-n
498 Move the selection cursor down N pages (default: 1).
499 .It Cm Up-arrow, k, Ctrl-p
500 Move the selection cursor up N pages (default: 1).
501 .It Cm Page-down, Space, Ctrl+f, f
502 Move the selection cursor down N pages (default: 1).
503 .It Cm Page-up, Ctrl+b, b
504 Move the selection cursor up N pages (default: 1).
506 Move the selection cursor down N half pages (default: 1).
508 Move the selection cursor up N half pages (default: 1).
510 Move the selection cursor to the first line of the file.
512 Move the selection cursor to the last line of the file.
514 Move the selection cursor to line N (default: 1).
518 but defaults to the last line in the file.
522 view for the currently selected line's commit.
526 view with the version of the file as found in the currently
527 selected line's commit.
531 view with the version of the file as found in the parent commit of the
532 currently selected line's commit.
536 view with the previously blamed commit.
540 view for the currently selected annotated line.
542 Prompt for a search pattern and start searching for matching lines.
543 The search pattern is an extended regular expression.
544 Regular expression syntax is documented in
547 Find the Nth next line which matches the current search pattern (default: 1).
549 Find the Nth previous line which matches the current search pattern
552 Change the diff algorithm.
553 Supported diff algorithms are Myers (quick and dirty) and
554 Patience (slow and tidy).
555 This is a global setting which also affects the
565 Start traversing history at the specified
567 The expected argument is a commit ID SHA1 hash, or a reference name or keyword
568 which will be resolved to a commit ID.
569 An abbreviated hash argument will be expanded to a full SHA1 hash
570 automatically, provided the abbreviation is unique.
575 resolve to the work tree's base commit and branch head, respectively.
576 The former is only valid if invoked in a work tree, while the latter will
577 resolve to the tip of the work tree's current branch if invoked in a
578 work tree, otherwise it will resolve to the repository's HEAD reference.
579 Keywords and references may be appended with
583 modifiers and an optional integer N to denote the
584 Nth descendant or antecedent by first parent traversal, respectively;
587 denotes the work tree branch head's 2nd generation ancestor, and
589 denotes the 4th generation descendant of the work tree's base commit.
592 will denote the 3rd generation descendant of the commit resolved by the
599 modifier without a trailing integer has an implicit
607 .It Fl r Ar repository-path
608 Use the repository at the specified path.
609 If not specified, assume the repository is located at or above the current
611 If this directory is a
613 work tree, use the repository path associated with this work tree.
618 .Op Fl r Ar repository-path
621 Display the repository tree.
624 is specified, show tree entries at this path.
626 Displayed tree entries may carry one of the following trailing annotations:
627 .Bl -column YXZ description
628 .It @ Ta entry is a symbolic link
629 .It / Ta entry is a directory
630 .It * Ta entry is an executable file
631 .It $ Ta entry is a Git submodule
634 Symbolic link entries are also annotated with the target path of the link.
638 are as follows (N denotes optional prefixed count modifier):
640 .It Cm Down-arrow, j, Ctrl-n
641 Move the selection cursor down N lines (default: 1).
642 .It Cm Up-arrow, k, Ctrl-p
643 Move the selection cursor up N lines (default: 1).
644 .It Cm Page-down, Space, Ctrl+f, f
645 Move the selection cursor down N pages (default: 1).
646 .It Cm Page-up, Ctrl+b, b
647 Move the selection cursor up N pages (default: 1).
649 Move the selection cursor down N half pages (default: 1).
651 Move the selection cursor up N half pages (default: 1).
653 Move the selection cursor to the first entry.
655 Move the selection cursor to the last entry.
657 Move the selection cursor to entry N (default: 1).
661 but defaults to the last entry.
663 Enter the currently selected directory, or switch to the
665 view for the currently selected file.
669 view for the currently selected tree entry.
673 view listing all references in the repository.
674 This can then be used to open a new
676 view for arbitrary branches and tags.
678 Move back to the Nth parent directory (default: 1).
680 Show object IDs for all objects displayed in the
684 Prompt for a search pattern and start searching for matching tree entries.
685 The search pattern is an extended regular expression which is matched
686 against the tree entry's name.
687 Regular expression syntax is documented in
690 Find the Nth next tree entry which matches the current search pattern
693 Find the Nth previous tree entry which matches the current search pattern
702 Start traversing history at the specified
704 The expected argument is a commit ID SHA1 hash, or a reference name or keyword
705 which will be resolved to a commit ID.
706 An abbreviated hash argument will be expanded to a full SHA1 hash
707 automatically, provided the abbreviation is unique.
712 resolve to the work tree's base commit and branch head, respectively.
713 The former is only valid if invoked in a work tree, while the latter will
714 resolve to the tip of the work tree's current branch if invoked in a
715 work tree, otherwise it will resolve to the repository's HEAD reference.
716 Keywords and references may be appended with
720 modifiers and an optional integer N to denote the
721 Nth descendant or antecedent by first parent traversal, respectively;
724 denotes the work tree branch head's 2nd generation ancestor, and
726 denotes the 4th generation descendant of the work tree's base commit.
729 will denote the 3rd generation descendant of the commit resolved by the
736 modifier without a trailing integer has an implicit
744 .It Fl r Ar repository-path
745 Use the repository at the specified path.
746 If not specified, assume the repository is located at or above the current
748 If this directory is a
750 work tree, use the repository path associated with this work tree.
752 .It Cm ref Op Fl r Ar repository-path
753 Display references in the repository.
757 are as follows (N denotes optional prefixed count modifier):
759 .It Cm Down-arrow, j, Ctrl-n
760 Move the selection cursor down N lines (default: 1).
761 .It Cm Up-arrow, k, Ctrl-p
762 Move the selection cursor up N lines (default: 1).
763 .It Cm Page-down, Space, Ctrl+f, f
764 Move the selection cursor down N pages (default: 1).
765 .It Cm Page-up, Ctrl+b, b
766 Move the selection cursor up N pages (default: 1).
768 Move the selection cursor down N half pages (default: 1).
770 Move the selection cursor up N half pages (default: 1).
772 Move the selection cursor to the first reference.
774 Move the selection cursor to the last reference.
776 Move the selection cursor to reference N (default: 1).
780 but defaults to the last reference.
784 view which begins traversing history at the commit resolved via the
785 currently selected reference.
789 view showing the tree resolved via the currently selected reference.
791 Show object IDs for all non-symbolic references displayed in the
795 Show last modified date of each displayed reference.
797 Toggle display order of references between sort by name and sort by timestamp.
799 Prompt for a search pattern and start searching for matching references.
800 The search pattern is an extended regular expression which is matched
801 against absolute reference names.
802 Regular expression syntax is documented in
805 Find the Nth next reference which matches the current search pattern
808 Find the Nth previous reference which matches the current search pattern
811 Reload the list of references displayed by the
820 .It Fl r Ar repository-path
821 Use the repository at the specified path.
822 If not specified, assume the repository is located at or above the current
824 If this directory is a
826 work tree, use the repository path associated with this work tree.
830 .Bl -tag -width TOG_VIEW_SPLIT_MODE
833 shows colorized output if this variable is set to a non-empty value.
834 The default color scheme can be modified by setting the environment
835 variables documented below.
836 The colors available in color schemes are
846 which maps to the terminal's default foreground color.
847 .It Ev TOG_COLOR_AUTHOR
848 The color used to mark up author information.
849 If not set, the default value
852 .It Ev TOG_COLOR_COMMIT
853 The color used to mark up commit IDs.
854 If not set, the default value
857 .It Ev TOG_COLOR_DATE
858 The color used to mark up date information.
859 If not set, the default value
862 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
863 The color used to mark up chunk header lines in diffs.
864 If not set, the default value
867 .It Ev TOG_COLOR_DIFF_META
868 The color used to mark up meta data in diffs.
869 If not set, the default value
872 .It Ev TOG_COLOR_DIFF_MINUS
873 The color used to mark up removed lines in diffs.
874 If not set, the default value
877 .It Ev TOG_COLOR_DIFF_PLUS
878 The color used to mark up added lines in diffs.
879 If not set, the default value
882 .It Ev TOG_COLOR_REFS_BACKUP
883 The color used to mark up references in the
886 If not set, the default value
889 .It Ev TOG_COLOR_REFS_HEADS
890 The color used to mark up references in the
893 If not set, the default value
896 .It Ev TOG_COLOR_REFS_REMOTES
897 The color used to mark up references in the
900 If not set, the default value
903 .It Ev TOG_COLOR_REFS_TAGS
904 The color used to mark up references in the
907 If not set, the default value
910 .It Ev TOG_COLOR_TREE_DIRECTORY
911 The color used to mark up directory tree entries.
912 If not set, the default value
915 .It Ev TOG_COLOR_TREE_EXECUTABLE
916 The color used to mark up executable file tree entries.
917 If not set, the default value
920 .It Ev TOG_COLOR_TREE_SUBMODULE
921 The color used to mark up submodule tree entries.
922 If not set, the default value
925 .It Ev TOG_COLOR_TREE_SYMLINK
926 The color used to mark up symbolic link tree entries.
927 If not set, the default value
930 .It Ev TOG_DIFF_ALGORITHM
931 Determines the default diff algorithm used by
933 Supported diff algorithms are Myers (quick and dirty) and
934 Patience (slow and tidy).
936 .Ev TOG_DIFF_ALGORITHM
941 If unset, the Patience diff algorithm will be used by default.
942 .It Ev TOG_VIEW_SPLIT_MODE
943 Determines the default layout of split-screen views.
949 will use horizontal split by default.
950 Otherwise, vertical split will be used.
953 key can be used to switch between vertical and horizontal split layout
960 .Xr git-repository 5 ,
963 .An Christian Weisgerber Aq Mt naddy@openbsd.org
964 .An Josh Rickmar Aq Mt jrick@zettaport.com
965 .An Joshua Stein Aq Mt jcs@openbsd.org
966 .An Mark Jamsek Aq Mt mark@jamsek.dev
967 .An Martin Pieuchot Aq Mt mpi@openbsd.org
968 .An Omar Polo Aq Mt op@openbsd.org
969 .An Stefan Sperling Aq Mt stsp@openbsd.org
970 .An Klemens Nanni Aq Mt kn@openbsd.org
