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 Page-down, Ctrl+f
108 Move the selection cursor down one page.
109 .It Cm Page-up, Ctrl+b
110 Move the selection cursor up one page.
112 Move the selection cursor down one half page.
114 Move the selection cursor up one half page.
116 Move the cursor to the newest commit.
118 Move the cursor to the oldest commit.
119 This will traverse all commits on the current branch which may take
120 a long time depending on the number of commits in branch history.
121 If needed, this operation can be cancelled with
126 view showing file changes made in the currently selected commit.
130 view showing the tree for the currently selected commit.
132 Show log entries for the parent directory of the currently selected path.
133 However when an active search is in progress or when additional commits
136 aborts the running operation.
138 Prompt for a search pattern and start searching for matching commits.
139 The search pattern is an extended regular expression which is matched
140 against a commit's author name, committer name, log message, and
142 Regular expression syntax is documented in
145 Find the next commit which matches the current search pattern.
146 Searching continues until either a match is found or the
150 Find the previous commit which matches the current search pattern.
151 Searching continues until either a match is found or the
157 view with new commits found in the repository.
161 view and toggle display of merged commits.
164 option determines whether merged commits are displayed initially.
168 view listing all references in the repository.
169 This can then be used to open a new
171 view for arbitrary branches and tags.
179 Display individual commits which were merged into the current branch
183 shows the linear history of the current branch only.
186 key binding can be used to toggle display of merged commits at run-time.
188 Start traversing history at the specified
190 The expected argument is the name of a branch or a commit ID SHA1 hash.
191 An abbreviated hash argument will be expanded to a full SHA1 hash
192 automatically, provided the abbreviation is unique.
193 If this option is not specified, default to the work tree's current branch
194 if invoked in a work tree, or to the repository's HEAD reference.
195 .It Fl r Ar repository-path
196 Use the repository at the specified path.
197 If not specified, assume the repository is located at or above the current
199 If this directory is a
201 work tree, use the repository path associated with this work tree.
203 .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
204 Display the differences between two objects in the repository.
205 Treat each of the two arguments as a reference, a tag name, or an object
206 ID SHA1 hash, and display differences between the corresponding objects.
207 Both objects must be of the same type (blobs, trees, or commits).
208 An abbreviated hash argument will be expanded to a full SHA1 hash
209 automatically, provided the abbreviation is unique.
216 Toggle treatment of file contents as ASCII text even if binary data was
218 .It Cm Down-arrow, j, Ctrl-n
220 .It Cm Up-arrow, k, Ctrl-p
222 .It Cm Page-down, Space, Ctrl+f
223 Scroll down one page.
224 .It Cm Page-up, Ctrl+b
227 Scroll down one half page.
229 Scroll up one half page.
231 Scroll to the top of the view.
233 Scroll to the bottom of the view.
235 Reduce the amount of diff context lines.
237 Increase the amount of diff context lines.
241 view was opened via the
243 view, move to the previous (younger) commit.
247 view was opened via the
249 view, move to the next (older) commit.
251 Prompt for a search pattern and start searching for matching lines.
252 The search pattern is an extended regular expression.
253 Regular expression syntax is documented in
256 Find the next line which matches the current search pattern.
258 Find the previous line which matches the current search pattern.
260 Toggle display of whitespace-only changes.
268 Treat file contents as ASCII text even if binary data is detected.
270 Set the number of context lines shown in the diff.
271 By default, 3 lines of context are shown.
272 .It Fl r Ar repository-path
273 Use the repository at the specified path.
274 If not specified, assume the repository is located at or above the current
276 If this directory is a
278 work tree, use the repository path associated with this work tree.
280 Ignore whitespace-only changes.
282 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
283 Display line-by-line history of a file at the specified path.
289 .It Cm Down-arrow, j, Ctrl-n
290 Move the selection cursor down.
291 .It Cm Up-arrow, k, Ctrl-p
292 Move the selection cursor up.
293 .It Cm Page-down, Space, Ctrl+f
294 Move the selection cursor down one page.
295 .It Cm Page-up, Ctrl+b
296 Move the selection cursor up one page.
298 Move the selection cursor down one half page.
300 Move the selection cursor up one half page.
302 Move the selection cursor to the first line of the file.
304 Move the selection cursor to the last line of the file.
308 view for the currently selected line's commit.
312 view with the version of the file as found in the currently
313 selected line's commit.
317 view with the version of the file as found in the parent commit of the
318 currently selected line's commit.
322 view with the previously blamed commit.
324 Prompt for a search pattern and start searching for matching lines.
325 The search pattern is an extended regular expression.
326 Regular expression syntax is documented in
329 Find the next line which matches the current search pattern.
331 Find the previous line which matches the current search pattern.
339 Start traversing history at the specified
341 The expected argument is the name of a branch or a commit ID SHA1 hash.
342 An abbreviated hash argument will be expanded to a full SHA1 hash
343 automatically, provided the abbreviation is unique.
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 .It Cm tree Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
353 Display the repository tree.
356 is specified, show tree entries at this path.
358 Displayed tree entries may carry one of the following trailing annotations:
359 .Bl -column YXZ description
360 .It @ Ta entry is a symbolic link
361 .It / Ta entry is a directory
362 .It * Ta entry is an executable file
363 .It $ Ta entry is a Git submodule
366 Symbolic link entries are also annotated with the target path of the link.
372 .It Cm Down-arrow, j, Ctrl-n
373 Move the selection cursor down.
374 .It Cm Up-arrow, k, Ctrl-p
375 Move the selection cursor up.
376 .It Cm Page-down, Ctrl+f
377 Move the selection cursor down one page.
378 .It Cm Page-up, Ctrl+b
379 Move the selection cursor up one page.
381 Move the selection cursor down one half page.
383 Move the selection cursor up one half page.
385 Move the selection cursor to the first entry.
387 Move the selection cursor to the last entry.
389 Enter the currently selected directory, or switch to the
391 view for the currently selected file.
395 view for the currently selected tree entry.
399 view listing all references in the repository.
400 This can then be used to open a new
402 view for arbitrary branches and tags.
404 Move back to the parent directory.
406 Show object IDs for all objects displayed in the
410 Prompt for a search pattern and start searching for matching tree entries.
411 The search pattern is an extended regular expression which is matched
412 against the tree entry's name.
413 Regular expression syntax is documented in
416 Find the next tree entry which matches the current search pattern.
418 Find the previous tree entry which matches the current search pattern.
426 Start traversing history at the specified
428 The expected argument is the name of a branch or a commit ID SHA1 hash.
429 An abbreviated hash argument will be expanded to a full SHA1 hash
430 automatically, provided the abbreviation is unique.
431 .It Fl r Ar repository-path
432 Use the repository at the specified path.
433 If not specified, assume the repository is located at or above the current
435 If this directory is a
437 work tree, use the repository path associated with this work tree.
439 .It Cm ref Oo Fl r Ar repository-path Oc
440 Display references in the repository.
446 .It Cm Down-arrow, j, Ctrl-n
447 Move the selection cursor down.
448 .It Cm Up-arrow, k, Ctrl-p
449 Move the selection cursor up.
450 .It Cm Page-down, Ctrl+f
451 Move the selection cursor down one page.
452 .It Cm Page-up, Ctrl+b
453 Move the selection cursor up one page.
455 Move the selection cursor down one half page.
457 Move the selection cursor up one half page.
459 Move the selection cursor to the first reference.
461 Move the selection cursor to the last reference.
465 view which begins traversing history at the commit resolved via the
466 currently selected reference.
470 view showing the tree resolved via the currently selected reference.
472 Show object IDs for all non-symbolic references displayed in the
476 Toggle display order of references between sort by name and sort by timestamp.
478 Prompt for a search pattern and start searching for matching references.
479 The search pattern is an extended regular expression which is matched
480 against absolute reference names.
481 Regular expression syntax is documented in
484 Find the next reference which matches the current search pattern.
486 Find the previous reference which matches the current search pattern.
488 Reload the list of references displayed by the
497 .It Fl r Ar repository-path
498 Use the repository at the specified path.
499 If not specified, assume the repository is located at or above the current
501 If this directory is a
503 work tree, use the repository path associated with this work tree.
507 .Bl -tag -width TOG_COLORS
510 shows colorized output if this variable is set to a non-empty value.
511 The default color scheme can be modified by setting the environment
512 variables documented below.
513 The colors available in color schemes are
523 which maps to the terminal's default foreground color.
524 .It Ev TOG_COLOR_DIFF_MINUS
525 The color used to mark up removed lines in diffs.
526 If not set, the default value
529 .It Ev TOG_COLOR_DIFF_PLUS
530 The color used to mark up added lines in diffs.
531 If not set, the default value
534 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
535 The color used to mark up chunk header lines in diffs.
536 If not set, the default value
539 .It Ev TOG_COLOR_DIFF_META
540 The color used to mark up meta data in diffs.
541 If not set, the default value
544 .It Ev TOG_COLOR_TREE_SUBMODULE
545 The color used to mark up submodule tree entries.
546 If not set, the default value
549 .It Ev TOG_COLOR_TREE_SYMLINK
550 The color used to mark up symbolic link tree entries.
551 If not set, the default value
554 .It Ev TOG_COLOR_TREE_DIRECTORY
555 The color used to mark up directory tree entries.
556 If not set, the default value
559 .It Ev TOG_COLOR_TREE_EXECUTABLE
560 The color used to mark up executable file tree entries.
561 If not set, the default value
564 .It Ev TOG_COLOR_COMMIT
565 The color used to mark up commit IDs.
566 If not set, the default value
569 .It Ev TOG_COLOR_AUTHOR
570 The color used to mark up author information.
571 If not set, the default value
574 .It Ev TOG_COLOR_DATE
575 The color used to mark up date information.
576 If not set, the default value
579 .It Ev TOG_COLOR_REFS_HEADS
580 The color used to mark up references in the
583 If not set, the default value
586 .It Ev TOG_COLOR_REFS_TAGS
587 The color used to mark up references in the
590 If not set, the default value
593 .It Ev TOG_COLOR_REFS_REMOTES
594 The color used to mark up references in the
597 If not set, the default value
600 .It Ev TOG_COLOR_REFS_BACKUP
601 The color used to mark up references in the
604 If not set, the default value
612 .Xr git-repository 5 ,
615 .An Stefan Sperling Aq Mt stsp@openbsd.org
616 .An Joshua Stein Aq Mt jcs@openbsd.org
