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 The global key bindings are:
71 Quit the view which is in focus.
73 Switch focus between views.
75 Toggle fullscreen mode for a split-screen view.
77 will automatically use split-screen views if the size of the terminal
78 window is sufficiently large.
81 Global options must precede the command name, and are as follows:
82 .Bl -tag -width tenletters
84 Display usage information.
86 Display program version and exit immediately.
93 .It Cm log Oo Fl b Oc Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
94 Display history of a repository.
97 is specified, show only commits which modified this path.
98 If invoked in a work tree, the
100 is interpreted relative to the current working directory,
101 and the work tree's path prefix is implicitly prepended.
102 Otherwise, the path is interpreted relative to the repository root.
104 This command is also executed if no explicit command is specified.
108 are as follows (N denotes optional prefixed count modifier):
110 .It Cm Down-arrow, j, >, Full stop, Ctrl-n
111 Move the selection cursor down N lines (default: 1).
112 .It Cm Up-arrow, k, <, Comma, Ctrl-p
113 Move the selection cursor up N lines (default: 1).
114 .It Cm Right-arrow, l
115 Scroll log message field to the right N increments (default: 1).
117 Log message moves left on the screen.
119 Scroll log message field to the left N increments (default: 1).
121 Log message moves right on the screen.
123 Scroll log message field to the rightmost position.
125 Scroll log message field to the leftmost position.
126 .It Cm Page-down, Space, Ctrl+f, f
127 Move the selection cursor down N pages (default: 1).
128 .It Cm Page-up, Ctrl+b, b
129 Move the selection cursor up N pages (default: 1).
131 Move the selection cursor down N half pages (default: 1).
133 Move the selection cursor up N half pages (default: 1).
135 Move the cursor to the newest commit.
137 Move the cursor to the oldest commit.
138 This will traverse all commits on the current branch which may take
139 a long time depending on the number of commits in branch history.
140 If needed, this operation can be cancelled with
145 view showing file changes made in the currently selected commit.
149 view showing the tree for the currently selected commit.
151 Show log entries for the parent directory of the currently selected path.
152 However when an active search is in progress or when additional commits
155 aborts the running operation.
157 Prompt for a search pattern and start searching for matching commits.
158 The search pattern is an extended regular expression which is matched
159 against a commit's author name, committer name, log message, and
161 Regular expression syntax is documented in
164 Find the Nth next commit which matches the current search pattern (default: 1).
166 Searching continues until either a match is found or the
170 Find the Nth previous commit which matches the current search pattern
173 Searching continues until either a match is found or the
179 view with new commits found in the repository.
183 view and toggle display of merged commits.
186 option determines whether merged commits are displayed initially.
190 view listing all references in the repository.
191 This can then be used to open a new
193 view for arbitrary branches and tags.
201 Display individual commits which were merged into the current branch
205 shows the linear history of the current branch only.
208 key binding can be used to toggle display of merged commits at run-time.
210 Start traversing history at the specified
212 The expected argument is the name of a branch or a commit ID SHA1 hash.
213 An abbreviated hash argument will be expanded to a full SHA1 hash
214 automatically, provided the abbreviation is unique.
215 If this option is not specified, default to the work tree's current branch
216 if invoked in a work tree, or to the repository's HEAD reference.
217 .It Fl r Ar repository-path
218 Use the repository at the specified path.
219 If not specified, assume the repository is located at or above the current
221 If this directory is a
223 work tree, use the repository path associated with this work tree.
225 .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
226 Display the differences between two objects in the repository.
227 Treat each of the two arguments as a reference, a tag name, or an object
228 ID SHA1 hash, and display differences between the corresponding objects.
229 Both objects must be of the same type (blobs, trees, or commits).
230 An abbreviated hash argument will be expanded to a full SHA1 hash
231 automatically, provided the abbreviation is unique.
235 are as follows (N denotes optional prefixed count modifier):
238 Toggle treatment of file contents as ASCII text even if binary data was
240 .It Cm Down-arrow, j, Ctrl-n
241 Scroll down N lines (default: 1).
242 .It Cm Up-arrow, k, Ctrl-p
243 Scroll up N lines (default: 1).
244 .It Cm Right-arrow, l
245 Scroll view to the right N increments (default: 1).
247 Diff output moves left on the screen.
249 Scroll view to the left N increments (default: 1).
251 Diff output moves right on the screen.
253 Scroll view to the rightmost position.
255 Scroll view left to the start of the line.
256 .It Cm Page-down, Space, Ctrl+f, f
257 Scroll down N pages (default: 1).
258 .It Cm Page-up, Ctrl+b, b
259 Scroll up N pages (default: 1).
261 Scroll down N half pages (default: 1).
263 Scroll up N half pages (default: 1).
265 Scroll to the top of the view.
267 Scroll to the bottom of the view.
269 Reduce diff context by N lines (default: 1).
271 Increase diff context by N lines (default: 1).
275 view was opened via the
277 view, move to the Nth previous (younger) commit (default: 1).
281 view was opened via the
283 view, move to the Nth next (older) commit (default: 1).
285 Prompt for a search pattern and start searching for matching lines.
286 The search pattern is an extended regular expression.
287 Regular expression syntax is documented in
290 Find the Nth next line which matches the current search pattern (default: 1).
292 Find the Nth previous line which matches the current search pattern
295 Toggle display of whitespace-only changes.
297 Change the diff algorithm.
298 Supported diff algorithms are Myers and Patience.
299 This is a global setting which also affects the
309 Treat file contents as ASCII text even if binary data is detected.
311 Set the number of context lines shown in the diff.
312 By default, 3 lines of context are shown.
313 .It Fl r Ar repository-path
314 Use the repository at the specified path.
315 If not specified, assume the repository is located at or above the current
317 If this directory is a
319 work tree, use the repository path associated with this work tree.
321 Ignore whitespace-only changes.
323 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
324 Display line-by-line history of a file at the specified path.
328 are as follows (N denotes optional prefixed count modifier):
330 .It Cm Down-arrow, j, Ctrl-n
331 Move the selection cursor down N pages (default: 1).
332 .It Cm Up-arrow, k, Ctrl-p
333 Move the selection cursor up N pages (default: 1).
334 .It Cm Right-arrow, l
335 Scroll view to the right N increments (default: 1).
337 File output moves left on the screen.
339 Scroll view to the left N increments (default: 1).
341 File output moves right on the screen.
343 Scroll view to the rightmost position.
345 Scroll view left to the start of the line.
346 .It Cm Page-down, Space, Ctrl+f, f
347 Move the selection cursor down N pages (default: 1).
348 .It Cm Page-up, Ctrl+b, b
349 Move the selection cursor up N pages (default: 1).
351 Move the selection cursor down N half pages (default: 1).
353 Move the selection cursor up N half pages (default: 1).
355 Move the selection cursor to the first line of the file.
357 Move the selection cursor to the last line of the file.
361 view for the currently selected line's commit.
365 view with the version of the file as found in the currently
366 selected line's commit.
370 view with the version of the file as found in the parent commit of the
371 currently selected line's commit.
375 view with the previously blamed commit.
377 Prompt for a search pattern and start searching for matching lines.
378 The search pattern is an extended regular expression.
379 Regular expression syntax is documented in
382 Find the Nth next line which matches the current search pattern (default: 1).
384 Find the Nth previous line which matches the current search pattern
387 Change the diff algorithm.
388 Supported diff algorithms are Myers and Patience.
389 This is a global setting which also affects the
399 Start traversing history at the specified
401 The expected argument is the name of a branch or a commit ID SHA1 hash.
402 An abbreviated hash argument will be expanded to a full SHA1 hash
403 automatically, provided the abbreviation is unique.
404 .It Fl r Ar repository-path
405 Use the repository at the specified path.
406 If not specified, assume the repository is located at or above the current
408 If this directory is a
410 work tree, use the repository path associated with this work tree.
412 .It Cm tree Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
413 Display the repository tree.
416 is specified, show tree entries at this path.
418 Displayed tree entries may carry one of the following trailing annotations:
419 .Bl -column YXZ description
420 .It @ Ta entry is a symbolic link
421 .It / Ta entry is a directory
422 .It * Ta entry is an executable file
423 .It $ Ta entry is a Git submodule
426 Symbolic link entries are also annotated with the target path of the link.
430 are as follows (N denotes optional prefixed count modifier):
432 .It Cm Down-arrow, j, Ctrl-n
433 Move the selection cursor down N lines (default: 1).
434 .It Cm Up-arrow, k, Ctrl-p
435 Move the selection cursor up N lines (default: 1).
436 .It Cm Page-down, Space, Ctrl+f, f
437 Move the selection cursor down N pages (default: 1).
438 .It Cm Page-up, Ctrl+b, b
439 Move the selection cursor up N pages (default: 1).
441 Move the selection cursor down N half pages (default: 1).
443 Move the selection cursor up N half pages (default: 1).
445 Move the selection cursor to the first entry.
447 Move the selection cursor to the last entry.
449 Enter the currently selected directory, or switch to the
451 view for the currently selected file.
455 view for the currently selected tree entry.
459 view listing all references in the repository.
460 This can then be used to open a new
462 view for arbitrary branches and tags.
464 Move back to the Nth parent directory (default: 1).
466 Show object IDs for all objects displayed in the
470 Prompt for a search pattern and start searching for matching tree entries.
471 The search pattern is an extended regular expression which is matched
472 against the tree entry's name.
473 Regular expression syntax is documented in
476 Find the Nth next tree entry which matches the current search pattern
479 Find the Nth previous tree entry which matches the current search pattern
488 Start traversing history at the specified
490 The expected argument is the name of a branch or a commit ID SHA1 hash.
491 An abbreviated hash argument will be expanded to a full SHA1 hash
492 automatically, provided the abbreviation is unique.
493 .It Fl r Ar repository-path
494 Use the repository at the specified path.
495 If not specified, assume the repository is located at or above the current
497 If this directory is a
499 work tree, use the repository path associated with this work tree.
501 .It Cm ref Oo Fl r Ar repository-path Oc
502 Display references in the repository.
506 are as follows (N denotes optional prefixed count modifier):
508 .It Cm Down-arrow, j, Ctrl-n
509 Move the selection cursor down N lines (default: 1).
510 .It Cm Up-arrow, k, Ctrl-p
511 Move the selection cursor up N lines (default: 1).
512 .It Cm Page-down, Space, Ctrl+f, f
513 Move the selection cursor down N pages (default: 1).
514 .It Cm Page-up, Ctrl+b, b
515 Move the selection cursor up N pages (default: 1).
517 Move the selection cursor down N half pages (default: 1).
519 Move the selection cursor up N half pages (default: 1).
521 Move the selection cursor to the first reference.
523 Move the selection cursor to the last reference.
527 view which begins traversing history at the commit resolved via the
528 currently selected reference.
532 view showing the tree resolved via the currently selected reference.
534 Show object IDs for all non-symbolic references displayed in the
538 Show last modified date of each displayed reference.
540 Toggle display order of references between sort by name and sort by timestamp.
542 Prompt for a search pattern and start searching for matching references.
543 The search pattern is an extended regular expression which is matched
544 against absolute reference names.
545 Regular expression syntax is documented in
548 Find the Nth next reference which matches the current search pattern
551 Find the Nth previous reference which matches the current search pattern
554 Reload the list of references displayed by the
563 .It Fl r Ar repository-path
564 Use the repository at the specified path.
565 If not specified, assume the repository is located at or above the current
567 If this directory is a
569 work tree, use the repository path associated with this work tree.
573 .Bl -tag -width TOG_DIFF_ALGORITHM
574 .It Ev TOG_DIFF_ALGORITHM
575 Determines the default diff algorithm used by
581 If unset, the Myers diff algorithm will be used by default.
584 shows colorized output if this variable is set to a non-empty value.
585 The default color scheme can be modified by setting the environment
586 variables documented below.
587 The colors available in color schemes are
597 which maps to the terminal's default foreground color.
598 .It Ev TOG_COLOR_DIFF_MINUS
599 The color used to mark up removed lines in diffs.
600 If not set, the default value
603 .It Ev TOG_COLOR_DIFF_PLUS
604 The color used to mark up added lines in diffs.
605 If not set, the default value
608 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
609 The color used to mark up chunk header lines in diffs.
610 If not set, the default value
613 .It Ev TOG_COLOR_DIFF_META
614 The color used to mark up meta data in diffs.
615 If not set, the default value
618 .It Ev TOG_COLOR_TREE_SUBMODULE
619 The color used to mark up submodule tree entries.
620 If not set, the default value
623 .It Ev TOG_COLOR_TREE_SYMLINK
624 The color used to mark up symbolic link tree entries.
625 If not set, the default value
628 .It Ev TOG_COLOR_TREE_DIRECTORY
629 The color used to mark up directory tree entries.
630 If not set, the default value
633 .It Ev TOG_COLOR_TREE_EXECUTABLE
634 The color used to mark up executable file tree entries.
635 If not set, the default value
638 .It Ev TOG_COLOR_COMMIT
639 The color used to mark up commit IDs.
640 If not set, the default value
643 .It Ev TOG_COLOR_AUTHOR
644 The color used to mark up author information.
645 If not set, the default value
648 .It Ev TOG_COLOR_DATE
649 The color used to mark up date information.
650 If not set, the default value
653 .It Ev TOG_COLOR_REFS_HEADS
654 The color used to mark up references in the
657 If not set, the default value
660 .It Ev TOG_COLOR_REFS_TAGS
661 The color used to mark up references in the
664 If not set, the default value
667 .It Ev TOG_COLOR_REFS_REMOTES
668 The color used to mark up references in the
671 If not set, the default value
674 .It Ev TOG_COLOR_REFS_BACKUP
675 The color used to mark up references in the
678 If not set, the default value
686 .Xr git-repository 5 ,
689 .An Stefan Sperling Aq Mt stsp@openbsd.org
690 .An Joshua Stein Aq Mt jcs@openbsd.org
