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
69 The global key bindings are:
75 Quit the view which is in focus.
77 Switch focus between views.
79 Toggle fullscreen mode for a split-screen view.
81 will automatically use split-screen views if the size of the terminal
82 window is sufficiently large.
84 Switch the current split-screen layout, and render all active views in
86 If the terminal is not wide enough when switching to a vertical split,
87 views will render in fullscreen.
89 When in a split-screen view, decrease the size of the focussed split
90 N increments (default: 1).
92 When in a split-screen view, increase the size of the focussed split
93 N increments (default: 1).
96 Global options must precede the command name, and are as follows:
97 .Bl -tag -width tenletters
99 Display usage information.
101 Display program version and exit immediately.
107 .Bl -tag -width blame
108 .It Cm log Oo Fl b Oc Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
109 Display history of a repository.
112 is specified, show only commits which modified this path.
113 If invoked in a work tree, the
115 is interpreted relative to the current working directory,
116 and the work tree's path prefix is implicitly prepended.
117 Otherwise, the path is interpreted relative to the repository root.
119 This command is also executed if no explicit command is specified.
123 are as follows (N denotes optional prefixed count modifier):
125 .It Cm Down-arrow, j, >, Full stop, Ctrl-n
126 Move the selection cursor down N lines (default: 1).
127 .It Cm Up-arrow, k, <, Comma, Ctrl-p
128 Move the selection cursor up N lines (default: 1).
129 .It Cm Right-arrow, l
130 Scroll log message field to the right N increments (default: 1).
132 Log message moves left on the screen.
134 Scroll log message field to the left N increments (default: 1).
136 Log message moves right on the screen.
138 Scroll log message field to the rightmost position.
140 Scroll log message field to the leftmost position.
141 .It Cm Page-down, Space, Ctrl+f, f
142 Move the selection cursor down N pages (default: 1).
143 .It Cm Page-up, Ctrl+b, b
144 Move the selection cursor up N pages (default: 1).
146 Move the selection cursor down N half pages (default: 1).
148 Move the selection cursor up N half pages (default: 1).
150 Move the cursor to the newest commit.
152 Move the cursor to the oldest commit.
153 This will traverse all commits on the current branch which may take
154 a long time depending on the number of commits in branch history.
155 If needed, this operation can be cancelled with
162 view showing file changes made in the currently selected commit.
166 view showing the tree for the currently selected commit.
168 Show log entries for the parent directory of the currently selected path.
169 However when an active search is in progress or when additional commits
172 aborts the running operation.
174 Prompt for a search pattern and start searching for matching commits.
175 The search pattern is an extended regular expression which is matched
176 against a commit's author name, committer name, log message, and
178 Regular expression syntax is documented in
181 Find the Nth next commit which matches the current search pattern (default: 1).
183 Searching continues until either a match is found or
189 Find the Nth previous commit which matches the current search pattern
192 Searching continues until either a match is found or
200 view with new commits found in the repository.
204 view and toggle display of merged commits.
207 option determines whether merged commits are displayed initially.
211 view listing all references in the repository.
212 This can then be used to open a new
214 view for arbitrary branches and tags.
222 Display individual commits which were merged into the current branch
226 shows the linear history of the current branch only.
229 key binding can be used to toggle display of merged commits at run-time.
231 Start traversing history at the specified
233 The expected argument is the name of a branch or a commit ID SHA1 hash.
234 An abbreviated hash argument will be expanded to a full SHA1 hash
235 automatically, provided the abbreviation is unique.
236 If this option is not specified, default to the work tree's current branch
237 if invoked in a work tree, or to the repository's HEAD reference.
238 .It Fl r Ar repository-path
239 Use the repository at the specified path.
240 If not specified, assume the repository is located at or above the current
242 If this directory is a
244 work tree, use the repository path associated with this work tree.
246 .It Cm diff Oo Fl a Oc Oo Fl C Ar number Oc Oo Fl r Ar repository-path Oc Oo Fl w Oc Ar object1 Ar object2
247 Display the differences between two objects in the repository.
248 Treat each of the two arguments as a reference, a tag name, or an object
249 ID SHA1 hash, and display differences between the corresponding objects.
250 Both objects must be of the same type (blobs, trees, or commits).
251 An abbreviated hash argument will be expanded to a full SHA1 hash
252 automatically, provided the abbreviation is unique.
256 are as follows (N denotes optional prefixed count modifier):
259 Toggle treatment of file contents as ASCII text even if binary data was
261 .It Cm Down-arrow, j, Ctrl-n
262 Scroll down N lines (default: 1).
263 .It Cm Up-arrow, k, Ctrl-p
264 Scroll up N lines (default: 1).
265 .It Cm Right-arrow, l
266 Scroll view to the right N increments (default: 1).
268 Diff output moves left on the screen.
270 Scroll view to the left N increments (default: 1).
272 Diff output moves right on the screen.
274 Scroll view to the rightmost position.
276 Scroll view left to the start of the line.
277 .It Cm Page-down, Space, Ctrl+f, f
278 Scroll down N pages (default: 1).
279 .It Cm Page-up, Ctrl+b, b
280 Scroll up N pages (default: 1).
282 Scroll down N half pages (default: 1).
284 Scroll up N half pages (default: 1).
286 Scroll to the top of the view.
288 Scroll to the bottom of the view.
290 Reduce diff context by N lines (default: 1).
292 Increase diff context by N lines (default: 1).
296 view was opened via the
298 view, move to the Nth previous (younger) commit.
299 If the diff was opened via the
301 view, move to the Nth previous line and load the corresponding commit
306 view was opened via the
308 view, move to the Nth next (older) commit.
309 If the diff was opened via the
311 view, move to the Nth next line and load the corresponding commit (default: 1).
313 Prompt for a search pattern and start searching for matching lines.
314 The search pattern is an extended regular expression.
315 Regular expression syntax is documented in
318 Find the Nth next line which matches the current search pattern (default: 1).
320 Find the Nth previous line which matches the current search pattern
323 Toggle display of whitespace-only changes.
325 Change the diff algorithm.
326 Supported diff algorithms are Myers (quick and dirty) and
327 Patience (slow and tidy).
328 This is a global setting which also affects the
338 Treat file contents as ASCII text even if binary data is detected.
340 Set the number of context lines shown in the diff.
341 By default, 3 lines of context are shown.
342 .It Fl r Ar repository-path
343 Use the repository at the specified path.
344 If not specified, assume the repository is located at or above the current
346 If this directory is a
348 work tree, use the repository path associated with this work tree.
350 Ignore whitespace-only changes.
352 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
353 Display line-by-line history of a file at the specified path.
357 are as follows (N denotes optional prefixed count modifier):
359 .It Cm Down-arrow, j, Ctrl-n
360 Move the selection cursor down N pages (default: 1).
361 .It Cm Up-arrow, k, Ctrl-p
362 Move the selection cursor up N pages (default: 1).
363 .It Cm Right-arrow, l
364 Scroll view to the right N increments (default: 1).
366 File output moves left on the screen.
368 Scroll view to the left N increments (default: 1).
370 File output moves right on the screen.
372 Scroll view to the rightmost position.
374 Scroll view left to the start of the line.
375 .It Cm Page-down, Space, Ctrl+f, f
376 Move the selection cursor down N pages (default: 1).
377 .It Cm Page-up, Ctrl+b, b
378 Move the selection cursor up N pages (default: 1).
380 Move the selection cursor down N half pages (default: 1).
382 Move the selection cursor up N half pages (default: 1).
384 Move the selection cursor to the first line of the file.
386 Move the selection cursor to the last line of the file.
390 view for the currently selected line's commit.
394 view with the version of the file as found in the currently
395 selected line's commit.
399 view with the version of the file as found in the parent commit of the
400 currently selected line's commit.
404 view with the previously blamed commit.
406 Prompt for a search pattern and start searching for matching lines.
407 The search pattern is an extended regular expression.
408 Regular expression syntax is documented in
411 Find the Nth next line which matches the current search pattern (default: 1).
413 Find the Nth previous line which matches the current search pattern
416 Change the diff algorithm.
417 Supported diff algorithms are Myers (quick and dirty) and
418 Patience (slow and tidy).
419 This is a global setting which also affects the
429 Start traversing history at the specified
431 The expected argument is the name of a branch or a commit ID SHA1 hash.
432 An abbreviated hash argument will be expanded to a full SHA1 hash
433 automatically, provided the abbreviation is unique.
434 .It Fl r Ar repository-path
435 Use the repository at the specified path.
436 If not specified, assume the repository is located at or above the current
438 If this directory is a
440 work tree, use the repository path associated with this work tree.
442 .It Cm tree Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
443 Display the repository tree.
446 is specified, show tree entries at this path.
448 Displayed tree entries may carry one of the following trailing annotations:
449 .Bl -column YXZ description
450 .It @ Ta entry is a symbolic link
451 .It / Ta entry is a directory
452 .It * Ta entry is an executable file
453 .It $ Ta entry is a Git submodule
456 Symbolic link entries are also annotated with the target path of the link.
460 are as follows (N denotes optional prefixed count modifier):
462 .It Cm Down-arrow, j, Ctrl-n
463 Move the selection cursor down N lines (default: 1).
464 .It Cm Up-arrow, k, Ctrl-p
465 Move the selection cursor up N lines (default: 1).
466 .It Cm Page-down, Space, Ctrl+f, f
467 Move the selection cursor down N pages (default: 1).
468 .It Cm Page-up, Ctrl+b, b
469 Move the selection cursor up N pages (default: 1).
471 Move the selection cursor down N half pages (default: 1).
473 Move the selection cursor up N half pages (default: 1).
475 Move the selection cursor to the first entry.
477 Move the selection cursor to the last entry.
479 Enter the currently selected directory, or switch to the
481 view for the currently selected file.
485 view for the currently selected tree entry.
489 view listing all references in the repository.
490 This can then be used to open a new
492 view for arbitrary branches and tags.
494 Move back to the Nth parent directory (default: 1).
496 Show object IDs for all objects displayed in the
500 Prompt for a search pattern and start searching for matching tree entries.
501 The search pattern is an extended regular expression which is matched
502 against the tree entry's name.
503 Regular expression syntax is documented in
506 Find the Nth next tree entry which matches the current search pattern
509 Find the Nth previous tree entry which matches the current search pattern
518 Start traversing history at the specified
520 The expected argument is the name of a branch or a commit ID SHA1 hash.
521 An abbreviated hash argument will be expanded to a full SHA1 hash
522 automatically, provided the abbreviation is unique.
523 .It Fl r Ar repository-path
524 Use the repository at the specified path.
525 If not specified, assume the repository is located at or above the current
527 If this directory is a
529 work tree, use the repository path associated with this work tree.
531 .It Cm ref Oo Fl r Ar repository-path Oc
532 Display references in the repository.
536 are as follows (N denotes optional prefixed count modifier):
538 .It Cm Down-arrow, j, Ctrl-n
539 Move the selection cursor down N lines (default: 1).
540 .It Cm Up-arrow, k, Ctrl-p
541 Move the selection cursor up N lines (default: 1).
542 .It Cm Page-down, Space, Ctrl+f, f
543 Move the selection cursor down N pages (default: 1).
544 .It Cm Page-up, Ctrl+b, b
545 Move the selection cursor up N pages (default: 1).
547 Move the selection cursor down N half pages (default: 1).
549 Move the selection cursor up N half pages (default: 1).
551 Move the selection cursor to the first reference.
553 Move the selection cursor to the last reference.
557 view which begins traversing history at the commit resolved via the
558 currently selected reference.
562 view showing the tree resolved via the currently selected reference.
564 Show object IDs for all non-symbolic references displayed in the
568 Show last modified date of each displayed reference.
570 Toggle display order of references between sort by name and sort by timestamp.
572 Prompt for a search pattern and start searching for matching references.
573 The search pattern is an extended regular expression which is matched
574 against absolute reference names.
575 Regular expression syntax is documented in
578 Find the Nth next reference which matches the current search pattern
581 Find the Nth previous reference which matches the current search pattern
584 Reload the list of references displayed by the
593 .It Fl r Ar repository-path
594 Use the repository at the specified path.
595 If not specified, assume the repository is located at or above the current
597 If this directory is a
599 work tree, use the repository path associated with this work tree.
603 .Bl -tag -width TOG_VIEW_SPLIT_MODE
604 .It Ev TOG_DIFF_ALGORITHM
605 Determines the default diff algorithm used by
607 Supported diff algorithms are Myers (quick and dirty) and
608 Patience (slow and tidy).
610 .Ev TOG_DIFF_ALGORITHM
615 If unset, the Myers diff algorithm will be used by default.
616 .It Ev TOG_VIEW_SPLIT_MODE
617 Determines the default layout of split-screen views.
623 will use horizontal split by default.
624 Otherwise, vertical split will be used.
627 key can be used to switch between vertical and horizontal split layout
631 shows colorized output if this variable is set to a non-empty value.
632 The default color scheme can be modified by setting the environment
633 variables documented below.
634 The colors available in color schemes are
644 which maps to the terminal's default foreground color.
645 .It Ev TOG_COLOR_DIFF_MINUS
646 The color used to mark up removed lines in diffs.
647 If not set, the default value
650 .It Ev TOG_COLOR_DIFF_PLUS
651 The color used to mark up added lines in diffs.
652 If not set, the default value
655 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
656 The color used to mark up chunk header lines in diffs.
657 If not set, the default value
660 .It Ev TOG_COLOR_DIFF_META
661 The color used to mark up meta data in diffs.
662 If not set, the default value
665 .It Ev TOG_COLOR_TREE_SUBMODULE
666 The color used to mark up submodule tree entries.
667 If not set, the default value
670 .It Ev TOG_COLOR_TREE_SYMLINK
671 The color used to mark up symbolic link tree entries.
672 If not set, the default value
675 .It Ev TOG_COLOR_TREE_DIRECTORY
676 The color used to mark up directory tree entries.
677 If not set, the default value
680 .It Ev TOG_COLOR_TREE_EXECUTABLE
681 The color used to mark up executable file tree entries.
682 If not set, the default value
685 .It Ev TOG_COLOR_COMMIT
686 The color used to mark up commit IDs.
687 If not set, the default value
690 .It Ev TOG_COLOR_AUTHOR
691 The color used to mark up author information.
692 If not set, the default value
695 .It Ev TOG_COLOR_DATE
696 The color used to mark up date information.
697 If not set, the default value
700 .It Ev TOG_COLOR_REFS_HEADS
701 The color used to mark up references in the
704 If not set, the default value
707 .It Ev TOG_COLOR_REFS_TAGS
708 The color used to mark up references in the
711 If not set, the default value
714 .It Ev TOG_COLOR_REFS_REMOTES
715 The color used to mark up references in the
718 If not set, the default value
721 .It Ev TOG_COLOR_REFS_BACKUP
722 The color used to mark up references in the
725 If not set, the default value
733 .Xr git-repository 5 ,
736 .An Christian Weisgerber Aq Mt naddy@openbsd.org
737 .An Josh Rickmar Aq Mt jrick@zettaport.com
738 .An Joshua Stein Aq Mt jcs@openbsd.org
739 .An Mark Jamsek Aq Mt mark@jamsek.dev
740 .An Martin Pieuchot Aq Mt mpi@openbsd.org
741 .An Omar Polo Aq Mt op@openbsd.org
742 .An Stefan Sperling Aq Mt stsp@openbsd.org
743 .An Klemens Nanni Aq Mt kn@openbsd.org
