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 The global key bindings are:
76 Quit the view which is in focus.
78 Switch focus between views.
80 Toggle fullscreen mode for a split-screen view.
82 will automatically use vertical split-screen views if the size of the
83 terminal window is sufficiently large.
85 Switch the current split-screen layout, and render all active views in
87 The split-screen layout can be either vertical or horizontal.
88 If the terminal is not wide enough when switching to a vertical split,
89 views will render in fullscreen.
91 When in a split-screen view, decrease the size of the focussed split
92 N increments (default: 1).
94 When in a split-screen view, increase the size of the focussed split
95 N increments (default: 1).
98 Global options must precede the command name, and are as follows:
99 .Bl -tag -width tenletters
101 Display usage information.
103 Display program version and exit immediately.
109 .Bl -tag -width blame
110 .It Cm log Oo Fl b Oc Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
111 Display history of a repository.
114 is specified, show only commits which modified this path.
115 If invoked in a work tree, the
117 is interpreted relative to the current working directory,
118 and the work tree's path prefix is implicitly prepended.
119 Otherwise, the path is interpreted relative to the repository root.
121 This command is also executed if no explicit command is specified.
125 are as follows (N denotes optional prefixed count modifier):
127 .It Cm Down-arrow, j, >, Full stop, Ctrl-n
128 Move the selection cursor down N lines (default: 1).
129 .It Cm Up-arrow, k, <, Comma, Ctrl-p
130 Move the selection cursor up N lines (default: 1).
131 .It Cm Right-arrow, l
132 Scroll log message field to the right N increments (default: 1).
134 Log message moves left on the screen.
136 Scroll log message field to the left N increments (default: 1).
138 Log message moves right on the screen.
140 Scroll log message field to the rightmost position.
142 Scroll log message field to the leftmost position.
143 .It Cm Page-down, Space, Ctrl+f, f
144 Move the selection cursor down N pages (default: 1).
145 .It Cm Page-up, Ctrl+b, b
146 Move the selection cursor up N pages (default: 1).
148 Move the selection cursor down N half pages (default: 1).
150 Move the selection cursor up N half pages (default: 1).
152 Move the cursor to the newest commit.
154 Move the cursor to the oldest commit.
155 This will traverse all commits on the current branch which may take
156 a long time depending on the number of commits in branch history.
157 If needed, this operation can be cancelled with
164 view showing file changes made in the currently selected commit.
168 view showing the tree for the currently selected commit.
170 Show log entries for the parent directory of the currently selected path.
171 However when an active search is in progress or when additional commits
174 aborts the running operation.
176 Prompt for a search pattern and start searching for matching commits.
177 The search pattern is an extended regular expression which is matched
178 against a commit's author name, committer name, log message, and
180 Regular expression syntax is documented in
183 Find the Nth next commit which matches the current search pattern (default: 1).
185 Searching continues until either a match is found or
191 Find the Nth previous commit which matches the current search pattern
194 Searching continues until either a match is found or
202 view with new commits found in the repository.
206 view and toggle display of merged commits.
209 option determines whether merged commits are displayed initially.
213 view listing all references in the repository.
214 This can then be used to open a new
216 view for arbitrary branches and tags.
224 Display individual commits which were merged into the current branch
228 shows the linear history of the current branch only.
231 key binding can be used to toggle display of merged commits at run-time.
233 Start traversing history at the specified
235 The expected argument is the name of a branch or a commit ID SHA1 hash.
236 An abbreviated hash argument will be expanded to a full SHA1 hash
237 automatically, provided the abbreviation is unique.
238 If this option is not specified, default to the work tree's current branch
239 if invoked in a work tree, or to the repository's HEAD reference.
240 .It Fl r Ar repository-path
241 Use the repository at the specified path.
242 If not specified, assume the repository is located at or above the current
244 If this directory is a
246 work tree, use the repository path associated with this work tree.
248 .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
249 Display the differences between two objects in the repository.
250 Treat each of the two arguments as a reference, a tag name, or an object
251 ID SHA1 hash, and display differences between the corresponding objects.
252 Both objects must be of the same type (blobs, trees, or commits).
253 An abbreviated hash argument will be expanded to a full SHA1 hash
254 automatically, provided the abbreviation is unique.
258 are as follows (N denotes optional prefixed count modifier):
261 Toggle treatment of file contents as ASCII text even if binary data was
263 .It Cm Down-arrow, j, Ctrl-n
264 Scroll down N lines (default: 1).
265 .It Cm Up-arrow, k, Ctrl-p
266 Scroll up N lines (default: 1).
267 .It Cm Right-arrow, l
268 Scroll view to the right N increments (default: 1).
270 Diff output moves left on the screen.
272 Scroll view to the left N increments (default: 1).
274 Diff output moves right on the screen.
276 Scroll view to the rightmost position.
278 Scroll view left to the start of the line.
279 .It Cm Page-down, Space, Ctrl+f, f
280 Scroll down N pages (default: 1).
281 .It Cm Page-up, Ctrl+b, b
282 Scroll up N pages (default: 1).
284 Scroll down N half pages (default: 1).
286 Scroll up N half pages (default: 1).
288 Scroll to the top of the view.
290 Scroll to the bottom of the view.
292 Reduce diff context by N lines (default: 1).
294 Increase diff context by N lines (default: 1).
298 view was opened via the
300 view, move to the Nth previous (younger) commit.
301 If the diff was opened via the
303 view, move to the Nth previous line and load the corresponding commit
308 view was opened via the
310 view, move to the Nth next (older) commit.
311 If the diff was opened via the
313 view, move to the Nth next line and load the corresponding commit (default: 1).
315 Prompt for a search pattern and start searching for matching lines.
316 The search pattern is an extended regular expression.
317 Regular expression syntax is documented in
320 Find the Nth next line which matches the current search pattern (default: 1).
322 Find the Nth previous line which matches the current search pattern
325 Toggle display of whitespace-only changes.
327 Change the diff algorithm.
328 Supported diff algorithms are Myers (quick and dirty) and
329 Patience (slow and tidy).
330 This is a global setting which also affects the
340 Treat file contents as ASCII text even if binary data is detected.
342 Set the number of context lines shown in the diff.
343 By default, 3 lines of context are shown.
344 .It Fl r Ar repository-path
345 Use the repository at the specified path.
346 If not specified, assume the repository is located at or above the current
348 If this directory is a
350 work tree, use the repository path associated with this work tree.
352 Ignore whitespace-only changes.
354 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
355 Display line-by-line history of a file at the specified path.
359 are as follows (N denotes optional prefixed count modifier):
361 .It Cm Down-arrow, j, Ctrl-n
362 Move the selection cursor down N pages (default: 1).
363 .It Cm Up-arrow, k, Ctrl-p
364 Move the selection cursor up N pages (default: 1).
365 .It Cm Right-arrow, l
366 Scroll view to the right N increments (default: 1).
368 File output moves left on the screen.
370 Scroll view to the left N increments (default: 1).
372 File output moves right on the screen.
374 Scroll view to the rightmost position.
376 Scroll view left to the start of the line.
377 .It Cm Page-down, Space, Ctrl+f, f
378 Move the selection cursor down N pages (default: 1).
379 .It Cm Page-up, Ctrl+b, b
380 Move the selection cursor up N pages (default: 1).
382 Move the selection cursor down N half pages (default: 1).
384 Move the selection cursor up N half pages (default: 1).
386 Move the selection cursor to the first line of the file.
388 Move the selection cursor to the last line of the file.
392 view for the currently selected line's commit.
396 view with the version of the file as found in the currently
397 selected line's commit.
401 view with the version of the file as found in the parent commit of the
402 currently selected line's commit.
406 view with the previously blamed commit.
408 Prompt for a search pattern and start searching for matching lines.
409 The search pattern is an extended regular expression.
410 Regular expression syntax is documented in
413 Find the Nth next line which matches the current search pattern (default: 1).
415 Find the Nth previous line which matches the current search pattern
418 Change the diff algorithm.
419 Supported diff algorithms are Myers (quick and dirty) and
420 Patience (slow and tidy).
421 This is a global setting which also affects the
431 Start traversing history at the specified
433 The expected argument is the name of a branch or a commit ID SHA1 hash.
434 An abbreviated hash argument will be expanded to a full SHA1 hash
435 automatically, provided the abbreviation is unique.
436 .It Fl r Ar repository-path
437 Use the repository at the specified path.
438 If not specified, assume the repository is located at or above the current
440 If this directory is a
442 work tree, use the repository path associated with this work tree.
444 .It Cm tree Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
445 Display the repository tree.
448 is specified, show tree entries at this path.
450 Displayed tree entries may carry one of the following trailing annotations:
451 .Bl -column YXZ description
452 .It @ Ta entry is a symbolic link
453 .It / Ta entry is a directory
454 .It * Ta entry is an executable file
455 .It $ Ta entry is a Git submodule
458 Symbolic link entries are also annotated with the target path of the link.
462 are as follows (N denotes optional prefixed count modifier):
464 .It Cm Down-arrow, j, Ctrl-n
465 Move the selection cursor down N lines (default: 1).
466 .It Cm Up-arrow, k, Ctrl-p
467 Move the selection cursor up N lines (default: 1).
468 .It Cm Page-down, Space, Ctrl+f, f
469 Move the selection cursor down N pages (default: 1).
470 .It Cm Page-up, Ctrl+b, b
471 Move the selection cursor up N pages (default: 1).
473 Move the selection cursor down N half pages (default: 1).
475 Move the selection cursor up N half pages (default: 1).
477 Move the selection cursor to the first entry.
479 Move the selection cursor to the last entry.
481 Enter the currently selected directory, or switch to the
483 view for the currently selected file.
487 view for the currently selected tree entry.
491 view listing all references in the repository.
492 This can then be used to open a new
494 view for arbitrary branches and tags.
496 Move back to the Nth parent directory (default: 1).
498 Show object IDs for all objects displayed in the
502 Prompt for a search pattern and start searching for matching tree entries.
503 The search pattern is an extended regular expression which is matched
504 against the tree entry's name.
505 Regular expression syntax is documented in
508 Find the Nth next tree entry which matches the current search pattern
511 Find the Nth previous tree entry which matches the current search pattern
520 Start traversing history at the specified
522 The expected argument is the name of a branch or a commit ID SHA1 hash.
523 An abbreviated hash argument will be expanded to a full SHA1 hash
524 automatically, provided the abbreviation is unique.
525 .It Fl r Ar repository-path
526 Use the repository at the specified path.
527 If not specified, assume the repository is located at or above the current
529 If this directory is a
531 work tree, use the repository path associated with this work tree.
533 .It Cm ref Oo Fl r Ar repository-path Oc
534 Display references in the repository.
538 are as follows (N denotes optional prefixed count modifier):
540 .It Cm Down-arrow, j, Ctrl-n
541 Move the selection cursor down N lines (default: 1).
542 .It Cm Up-arrow, k, Ctrl-p
543 Move the selection cursor up N lines (default: 1).
544 .It Cm Page-down, Space, Ctrl+f, f
545 Move the selection cursor down N pages (default: 1).
546 .It Cm Page-up, Ctrl+b, b
547 Move the selection cursor up N pages (default: 1).
549 Move the selection cursor down N half pages (default: 1).
551 Move the selection cursor up N half pages (default: 1).
553 Move the selection cursor to the first reference.
555 Move the selection cursor to the last reference.
559 view which begins traversing history at the commit resolved via the
560 currently selected reference.
564 view showing the tree resolved via the currently selected reference.
566 Show object IDs for all non-symbolic references displayed in the
570 Show last modified date of each displayed reference.
572 Toggle display order of references between sort by name and sort by timestamp.
574 Prompt for a search pattern and start searching for matching references.
575 The search pattern is an extended regular expression which is matched
576 against absolute reference names.
577 Regular expression syntax is documented in
580 Find the Nth next reference which matches the current search pattern
583 Find the Nth previous reference which matches the current search pattern
586 Reload the list of references displayed by the
595 .It Fl r Ar repository-path
596 Use the repository at the specified path.
597 If not specified, assume the repository is located at or above the current
599 If this directory is a
601 work tree, use the repository path associated with this work tree.
605 .Bl -tag -width TOG_VIEW_SPLIT_MODE
606 .It Ev TOG_DIFF_ALGORITHM
607 Determines the default diff algorithm used by
609 Supported diff algorithms are Myers (quick and dirty) and
610 Patience (slow and tidy).
612 .Ev TOG_DIFF_ALGORITHM
617 If unset, the Myers diff algorithm will be used by default.
618 .It Ev TOG_VIEW_SPLIT_MODE
619 Determines the default layout of split-screen views.
625 will use horizontal split by default.
626 Otherwise, vertical split will be used.
629 key can be used to switch between vertical and horizontal split layout
633 shows colorized output if this variable is set to a non-empty value.
634 The default color scheme can be modified by setting the environment
635 variables documented below.
636 The colors available in color schemes are
646 which maps to the terminal's default foreground color.
647 .It Ev TOG_COLOR_DIFF_MINUS
648 The color used to mark up removed lines in diffs.
649 If not set, the default value
652 .It Ev TOG_COLOR_DIFF_PLUS
653 The color used to mark up added lines in diffs.
654 If not set, the default value
657 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
658 The color used to mark up chunk header lines in diffs.
659 If not set, the default value
662 .It Ev TOG_COLOR_DIFF_META
663 The color used to mark up meta data in diffs.
664 If not set, the default value
667 .It Ev TOG_COLOR_TREE_SUBMODULE
668 The color used to mark up submodule tree entries.
669 If not set, the default value
672 .It Ev TOG_COLOR_TREE_SYMLINK
673 The color used to mark up symbolic link tree entries.
674 If not set, the default value
677 .It Ev TOG_COLOR_TREE_DIRECTORY
678 The color used to mark up directory tree entries.
679 If not set, the default value
682 .It Ev TOG_COLOR_TREE_EXECUTABLE
683 The color used to mark up executable file tree entries.
684 If not set, the default value
687 .It Ev TOG_COLOR_COMMIT
688 The color used to mark up commit IDs.
689 If not set, the default value
692 .It Ev TOG_COLOR_AUTHOR
693 The color used to mark up author information.
694 If not set, the default value
697 .It Ev TOG_COLOR_DATE
698 The color used to mark up date information.
699 If not set, the default value
702 .It Ev TOG_COLOR_REFS_HEADS
703 The color used to mark up references in the
706 If not set, the default value
709 .It Ev TOG_COLOR_REFS_TAGS
710 The color used to mark up references in the
713 If not set, the default value
716 .It Ev TOG_COLOR_REFS_REMOTES
717 The color used to mark up references in the
720 If not set, the default value
723 .It Ev TOG_COLOR_REFS_BACKUP
724 The color used to mark up references in the
727 If not set, the default value
735 .Xr git-repository 5 ,
738 .An Christian Weisgerber Aq Mt naddy@openbsd.org
739 .An Josh Rickmar Aq Mt jrick@zettaport.com
740 .An Joshua Stein Aq Mt jcs@openbsd.org
741 .An Mark Jamsek Aq Mt mark@jamsek.dev
742 .An Martin Pieuchot Aq Mt mpi@openbsd.org
743 .An Omar Polo Aq Mt op@openbsd.org
744 .An Stefan Sperling Aq Mt stsp@openbsd.org
745 .An Klemens Nanni Aq Mt kn@openbsd.org
