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 The global key bindings are:
64 Quit the view which is in focus.
66 Switch focus between views.
68 Toggle fullscreen mode for a split-screen view.
70 will automatically use split-screen views if the size of the terminal
71 window is sufficiently large.
74 Global options must precede the command name, and are as follows:
75 .Bl -tag -width tenletters
77 Display usage information.
79 Display program version and exit immediately.
86 .It Cm log Oo Fl b Oc Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
87 Display history of a repository.
90 is specified, show only commits which modified this path.
91 If invoked in a work tree, the
93 is interpreted relative to the current working directory,
94 and the work tree's path prefix is implicitly prepended.
95 Otherwise, the path is interpreted relative to the repository root.
97 This command is also executed if no explicit command is specified.
103 .It Cm Down-arrow, j, >, Full stop, Ctrl-n
104 Move the selection cursor down.
105 .It Cm Up-arrow, k, <, Comma, Ctrl-p
106 Move the selection cursor up.
107 .It Cm Right-arrow, l
108 Scroll log message field to the right.
109 Log message moves left on the screen.
111 Scroll log message field to the left.
112 Log message moves right on the screen.
114 Scroll log message field to the rightmost position.
116 Scroll log message field to the leftmost position.
117 .It Cm Page-down, Ctrl+f
118 Move the selection cursor down one page.
119 .It Cm Page-up, Ctrl+b
120 Move the selection cursor up one page.
122 Move the selection cursor down one half page.
124 Move the selection cursor up one half page.
126 Move the cursor to the newest commit.
128 Move the cursor to the oldest commit.
129 This will traverse all commits on the current branch which may take
130 a long time depending on the number of commits in branch history.
131 If needed, this operation can be cancelled with
136 view showing file changes made in the currently selected commit.
140 view showing the tree for the currently selected commit.
142 Show log entries for the parent directory of the currently selected path.
143 However when an active search is in progress or when additional commits
146 aborts the running operation.
148 Prompt for a search pattern and start searching for matching commits.
149 The search pattern is an extended regular expression which is matched
150 against a commit's author name, committer name, log message, and
152 Regular expression syntax is documented in
155 Find the next commit which matches the current search pattern.
156 Searching continues until either a match is found or the
160 Find the previous commit which matches the current search pattern.
161 Searching continues until either a match is found or the
167 view with new commits found in the repository.
171 view and toggle display of merged commits.
174 option determines whether merged commits are displayed initially.
178 view listing all references in the repository.
179 This can then be used to open a new
181 view for arbitrary branches and tags.
189 Display individual commits which were merged into the current branch
193 shows the linear history of the current branch only.
196 key binding can be used to toggle display of merged commits at run-time.
198 Start traversing history at the specified
200 The expected argument is the name of a branch or a commit ID SHA1 hash.
201 An abbreviated hash argument will be expanded to a full SHA1 hash
202 automatically, provided the abbreviation is unique.
203 If this option is not specified, default to the work tree's current branch
204 if invoked in a work tree, or to the repository's HEAD reference.
205 .It Fl r Ar repository-path
206 Use the repository at the specified path.
207 If not specified, assume the repository is located at or above the current
209 If this directory is a
211 work tree, use the repository path associated with this work tree.
213 .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
214 Display the differences between two objects in the repository.
215 Treat each of the two arguments as a reference, a tag name, or an object
216 ID SHA1 hash, and display differences between the corresponding objects.
217 Both objects must be of the same type (blobs, trees, or commits).
218 An abbreviated hash argument will be expanded to a full SHA1 hash
219 automatically, provided the abbreviation is unique.
226 Toggle treatment of file contents as ASCII text even if binary data was
228 .It Cm Down-arrow, j, Ctrl-n
230 .It Cm Up-arrow, k, Ctrl-p
232 .It Cm Right-arrow, l
233 Scroll view to the right.
234 Diff output moves left on the screen.
236 Scroll view to the left.
237 Diff output moves right on the screen.
239 Scroll view to the rightmost position.
241 Scroll view left to the start of the line.
242 .It Cm Page-down, Space, Ctrl+f
243 Scroll down one page.
244 .It Cm Page-up, Ctrl+b
247 Scroll down one half page.
249 Scroll up one half page.
251 Scroll to the top of the view.
253 Scroll to the bottom of the view.
255 Reduce the amount of diff context lines.
257 Increase the amount of diff context lines.
261 view was opened via the
263 view, move to the previous (younger) commit.
267 view was opened via the
269 view, move to the next (older) commit.
271 Prompt for a search pattern and start searching for matching lines.
272 The search pattern is an extended regular expression.
273 Regular expression syntax is documented in
276 Find the next line which matches the current search pattern.
278 Find the previous line which matches the current search pattern.
280 Toggle display of whitespace-only changes.
288 Treat file contents as ASCII text even if binary data is detected.
290 Set the number of context lines shown in the diff.
291 By default, 3 lines of context are shown.
292 .It Fl r Ar repository-path
293 Use the repository at the specified path.
294 If not specified, assume the repository is located at or above the current
296 If this directory is a
298 work tree, use the repository path associated with this work tree.
300 Ignore whitespace-only changes.
302 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
303 Display line-by-line history of a file at the specified path.
309 .It Cm Down-arrow, j, Ctrl-n
310 Move the selection cursor down.
311 .It Cm Up-arrow, k, Ctrl-p
312 Move the selection cursor up.
313 .It Cm Right-arrow, l
314 Scroll view to the right.
315 File output moves left on the screen.
317 Scroll view to the left.
318 File output moves right on the screen.
320 Scroll view to the rightmost position.
322 Scroll view left to the start of the line.
323 .It Cm Page-down, Space, Ctrl+f
324 Move the selection cursor down one page.
325 .It Cm Page-up, Ctrl+b
326 Move the selection cursor up one page.
328 Move the selection cursor down one half page.
330 Move the selection cursor up one half page.
332 Move the selection cursor to the first line of the file.
334 Move the selection cursor to the last line of the file.
338 view for the currently selected line's commit.
342 view with the version of the file as found in the currently
343 selected line's commit.
347 view with the version of the file as found in the parent commit of the
348 currently selected line's commit.
352 view with the previously blamed commit.
354 Prompt for a search pattern and start searching for matching lines.
355 The search pattern is an extended regular expression.
356 Regular expression syntax is documented in
359 Find the next line which matches the current search pattern.
361 Find the previous line which matches the current search pattern.
369 Start traversing history at the specified
371 The expected argument is the name of a branch or a commit ID SHA1 hash.
372 An abbreviated hash argument will be expanded to a full SHA1 hash
373 automatically, provided the abbreviation is unique.
374 .It Fl r Ar repository-path
375 Use the repository at the specified path.
376 If not specified, assume the repository is located at or above the current
378 If this directory is a
380 work tree, use the repository path associated with this work tree.
382 .It Cm tree Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
383 Display the repository tree.
386 is specified, show tree entries at this path.
388 Displayed tree entries may carry one of the following trailing annotations:
389 .Bl -column YXZ description
390 .It @ Ta entry is a symbolic link
391 .It / Ta entry is a directory
392 .It * Ta entry is an executable file
393 .It $ Ta entry is a Git submodule
396 Symbolic link entries are also annotated with the target path of the link.
402 .It Cm Down-arrow, j, Ctrl-n
403 Move the selection cursor down.
404 .It Cm Up-arrow, k, Ctrl-p
405 Move the selection cursor up.
406 .It Cm Page-down, Ctrl+f
407 Move the selection cursor down one page.
408 .It Cm Page-up, Ctrl+b
409 Move the selection cursor up one page.
411 Move the selection cursor down one half page.
413 Move the selection cursor up one half page.
415 Move the selection cursor to the first entry.
417 Move the selection cursor to the last entry.
419 Enter the currently selected directory, or switch to the
421 view for the currently selected file.
425 view for the currently selected tree entry.
429 view listing all references in the repository.
430 This can then be used to open a new
432 view for arbitrary branches and tags.
434 Move back to the parent directory.
436 Show object IDs for all objects displayed in the
440 Prompt for a search pattern and start searching for matching tree entries.
441 The search pattern is an extended regular expression which is matched
442 against the tree entry's name.
443 Regular expression syntax is documented in
446 Find the next tree entry which matches the current search pattern.
448 Find the previous tree entry which matches the current search pattern.
456 Start traversing history at the specified
458 The expected argument is the name of a branch or a commit ID SHA1 hash.
459 An abbreviated hash argument will be expanded to a full SHA1 hash
460 automatically, provided the abbreviation is unique.
461 .It Fl r Ar repository-path
462 Use the repository at the specified path.
463 If not specified, assume the repository is located at or above the current
465 If this directory is a
467 work tree, use the repository path associated with this work tree.
469 .It Cm ref Oo Fl r Ar repository-path Oc
470 Display references in the repository.
476 .It Cm Down-arrow, j, Ctrl-n
477 Move the selection cursor down.
478 .It Cm Up-arrow, k, Ctrl-p
479 Move the selection cursor up.
480 .It Cm Page-down, Ctrl+f
481 Move the selection cursor down one page.
482 .It Cm Page-up, Ctrl+b
483 Move the selection cursor up one page.
485 Move the selection cursor down one half page.
487 Move the selection cursor up one half page.
489 Move the selection cursor to the first reference.
491 Move the selection cursor to the last reference.
495 view which begins traversing history at the commit resolved via the
496 currently selected reference.
500 view showing the tree resolved via the currently selected reference.
502 Show object IDs for all non-symbolic references displayed in the
506 Show last modified date of each displayed reference.
508 Toggle display order of references between sort by name and sort by timestamp.
510 Prompt for a search pattern and start searching for matching references.
511 The search pattern is an extended regular expression which is matched
512 against absolute reference names.
513 Regular expression syntax is documented in
516 Find the next reference which matches the current search pattern.
518 Find the previous reference which matches the current search pattern.
520 Reload the list of references displayed by the
529 .It Fl r Ar repository-path
530 Use the repository at the specified path.
531 If not specified, assume the repository is located at or above the current
533 If this directory is a
535 work tree, use the repository path associated with this work tree.
539 .Bl -tag -width TOG_COLORS
542 shows colorized output if this variable is set to a non-empty value.
543 The default color scheme can be modified by setting the environment
544 variables documented below.
545 The colors available in color schemes are
555 which maps to the terminal's default foreground color.
556 .It Ev TOG_COLOR_DIFF_MINUS
557 The color used to mark up removed lines in diffs.
558 If not set, the default value
561 .It Ev TOG_COLOR_DIFF_PLUS
562 The color used to mark up added lines in diffs.
563 If not set, the default value
566 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
567 The color used to mark up chunk header lines in diffs.
568 If not set, the default value
571 .It Ev TOG_COLOR_DIFF_META
572 The color used to mark up meta data in diffs.
573 If not set, the default value
576 .It Ev TOG_COLOR_TREE_SUBMODULE
577 The color used to mark up submodule tree entries.
578 If not set, the default value
581 .It Ev TOG_COLOR_TREE_SYMLINK
582 The color used to mark up symbolic link tree entries.
583 If not set, the default value
586 .It Ev TOG_COLOR_TREE_DIRECTORY
587 The color used to mark up directory tree entries.
588 If not set, the default value
591 .It Ev TOG_COLOR_TREE_EXECUTABLE
592 The color used to mark up executable file tree entries.
593 If not set, the default value
596 .It Ev TOG_COLOR_COMMIT
597 The color used to mark up commit IDs.
598 If not set, the default value
601 .It Ev TOG_COLOR_AUTHOR
602 The color used to mark up author information.
603 If not set, the default value
606 .It Ev TOG_COLOR_DATE
607 The color used to mark up date information.
608 If not set, the default value
611 .It Ev TOG_COLOR_REFS_HEADS
612 The color used to mark up references in the
615 If not set, the default value
618 .It Ev TOG_COLOR_REFS_TAGS
619 The color used to mark up references in the
622 If not set, the default value
625 .It Ev TOG_COLOR_REFS_REMOTES
626 The color used to mark up references in the
629 If not set, the default value
632 .It Ev TOG_COLOR_REFS_BACKUP
633 The color used to mark up references in the
636 If not set, the default value
644 .Xr git-repository 5 ,
647 .An Stefan Sperling Aq Mt stsp@openbsd.org
648 .An Joshua Stein Aq Mt jcs@openbsd.org
