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
33 is an interactive read-only browser for Git repositories.
34 This repository format is described in
35 .Xr git-repository 5 .
38 supports several types of views which display repository data:
41 Displays commits in the repository's history.
42 This view is displayed initially if no
44 is specified, or if just a
48 Displays changes made in a particular commit.
50 Displays the line-by-line history of a file.
52 Displays the tree corresponding to a particular commit.
54 Displays references in the repository.
58 provides global and command-specific key bindings and options.
59 The global key bindings are:
65 Quit the view which is in focus.
67 Switch focus between views.
69 Toggle fullscreen mode for a split-screen view.
71 will automatically use split-screen views if the size of the terminal
72 window is sufficiently large.
75 Global options must precede the command name, and are as follows:
76 .Bl -tag -width tenletters
78 Display usage information.
80 Display program version and exit immediately.
87 .It Cm log Oo Fl b Oc Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
88 Display history of a repository.
91 is specified, show only commits which modified this path.
92 If invoked in a work tree, the
94 is interpreted relative to the current working directory,
95 and the work tree's path prefix is implicitly prepended.
96 Otherwise, the path is interpreted relative to the repository root.
98 This command is also executed if no explicit command is specified.
104 .It Cm Down-arrow, j, >, Full stop
105 Move the selection cursor down.
106 .It Cm Up-arrow, k, <, Comma
107 Move the selection cursor up.
108 .It Cm Page-down, Ctrl+f
109 Move the selection cursor down one page.
110 .It Cm Page-up, Ctrl+b
111 Move the selection cursor up one page.
115 view showing file changes made in the currently selected commit.
119 view showing the tree for the currently selected commit.
121 Show log entries for the parent directory of the currently selected path,
122 unless an active search is in progress in which case
126 Prompt for a search pattern and start searching for matching commits.
127 The search pattern is an extended regular expression which is matched
128 against a commit's author name, committer name, log message, and
130 Regular expression syntax is documented in
133 Find the next commit which matches the current search pattern.
134 Searching continues until either a match is found or the
138 Find the previous commit which matches the current search pattern.
139 Searching continues until either a match is found or the
145 view with new commits found in the repository.
149 view and toggle display of merged commits.
152 option determines whether merged commits are displayed initially.
156 view listing all references in the repository.
157 This can then be used to open a new
159 view for arbitrary branches and tags.
167 Display individual commits which were merged into the current branch
171 shows the linear history of the current branch only.
174 key binding can be used to toggle display of merged commits at run-time.
176 Start traversing history at the specified
178 The expected argument is the name of a branch or a commit ID SHA1 hash.
179 An abbreviated hash argument will be expanded to a full SHA1 hash
180 automatically, provided the abbreviation is unique.
181 If this option is not specified, default to the work tree's current branch
182 if invoked in a work tree, or to the repository's HEAD reference.
183 .It Fl r Ar repository-path
184 Use the repository at the specified path.
185 If not specified, assume the repository is located at or above the current
187 If this directory is a
189 work tree, use the repository path associated with this work tree.
191 .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
192 Display the differences between two objects in the repository.
193 Treat each of the two arguments as a reference, a tag name, or an object
194 ID SHA1 hash, and display differences between the corresponding objects.
195 Both objects must be of the same type (blobs, trees, or commits).
196 An abbreviated hash argument will be expanded to a full SHA1 hash
197 automatically, provided the abbreviation is unique.
204 Toggle treatment of file contents as ASCII text even if binary data was
210 .It Cm Page-down, Space, Ctrl+f
211 Scroll down one page.
212 .It Cm Page-up, Ctrl+b
215 Reduce the amount of diff context lines.
217 Increase the amount of diff context lines.
221 view was opened via the
223 view, move to the previous (younger) commit.
227 view was opened via the
229 view, move to the next (older) commit.
231 Prompt for a search pattern and start searching for matching lines.
232 The search pattern is an extended regular expression.
233 Regular expression syntax is documented in
236 Find the next line which matches the current search pattern.
238 Find the previous line which matches the current search pattern.
240 Toggle display of whitespace-only changes.
248 Treat file contents as ASCII text even if binary data is detected.
250 Set the number of context lines shown in the diff.
251 By default, 3 lines of context are shown.
252 .It Fl r Ar repository-path
253 Use the repository at the specified path.
254 If not specified, assume the repository is located at or above the current
256 If this directory is a
258 work tree, use the repository path associated with this work tree.
260 Ignore whitespace-only changes.
262 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
263 Display line-by-line history of a file at the specified path.
270 Move the selection cursor down.
272 Move the selection cursor up.
273 .It Cm Page-down, Space, Ctrl+f
274 Move the selection cursor down one page.
275 .It Cm Page-up, Ctrl+b
276 Move the selection cursor up one page.
280 view for the currently selected line's commit.
284 view with the version of the file as found in the currently
285 selected line's commit.
289 view with the version of the file as found in the parent commit of the
290 currently selected line's commit.
294 view with the previously blamed commit.
296 Prompt for a search pattern and start searching for matching lines.
297 The search pattern is an extended regular expression.
298 Regular expression syntax is documented in
301 Find the next line which matches the current search pattern.
303 Find the previous line which matches the current search pattern.
311 Start traversing history at the specified
313 The expected argument is the name of a branch or a commit ID SHA1 hash.
314 An abbreviated hash argument will be expanded to a full SHA1 hash
315 automatically, provided the abbreviation is unique.
316 .It Fl r Ar repository-path
317 Use the repository at the specified path.
318 If not specified, assume the repository is located at or above the current
320 If this directory is a
322 work tree, use the repository path associated with this work tree.
324 .It Cm tree Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Op Ar path
325 Display the repository tree.
328 is specified, show tree entries at this path.
330 Displayed tree entries may carry one of the following trailing annotations:
331 .Bl -column YXZ description
332 .It @ Ta entry is a symbolic link
333 .It / Ta entry is a directory
334 .It * Ta entry is an executable file
335 .It $ Ta entry is a Git submodule
338 Symbolic link entries are also annotated with the target path of the link.
345 Move the selection cursor down.
347 Move the selection cursor up.
348 .It Cm Page-down, Ctrl+f
349 Move the selection cursor down one page.
350 .It Cm Page-up, Ctrl+b
351 Move the selection cursor up one page.
353 Enter the currently selected directory, or switch to the
355 view for the currently selected file.
359 view for the currently selected tree entry.
363 view listing all references in the repository.
364 This can then be used to open a new
366 view for arbitrary branches and tags.
368 Move back to the parent directory.
370 Show object IDs for all objects displayed in the
374 Prompt for a search pattern and start searching for matching tree entries.
375 The search pattern is an extended regular expression which is matched
376 against the tree entry's name.
377 Regular expression syntax is documented in
380 Find the next tree entry which matches the current search pattern.
382 Find the previous tree entry which matches the current search pattern.
390 Start traversing history at the specified
392 The expected argument is the name of a branch or a commit ID SHA1 hash.
393 An abbreviated hash argument will be expanded to a full SHA1 hash
394 automatically, provided the abbreviation is unique.
395 .It Fl r Ar repository-path
396 Use the repository at the specified path.
397 If not specified, assume the repository is located at or above the current
399 If this directory is a
401 work tree, use the repository path associated with this work tree.
403 .It Cm ref Oo Fl r Ar repository-path Oc
404 Display references in the repository.
411 Move the selection cursor down.
413 Move the selection cursor up.
414 .It Cm Page-down, Ctrl+f
415 Move the selection cursor down one page.
416 .It Cm Page-up, Ctrl+b
417 Move the selection cursor up one page.
421 view which begins traversing history at the commit resolved via the
422 currently selected reference.
426 view showing the tree resolved via the currently selected reference.
428 Show object IDs for all non-symbolic references displayed in the
432 Prompt for a search pattern and start searching for matching references.
433 The search pattern is an extended regular expression which is matched
434 against absolute reference names.
435 Regular expression syntax is documented in
438 Find the next reference which matches the current search pattern.
440 Find the previous reference which matches the current search pattern.
442 Reload the list of references displayed by the
451 .It Fl r Ar repository-path
452 Use the repository at the specified path.
453 If not specified, assume the repository is located at or above the current
455 If this directory is a
457 work tree, use the repository path associated with this work tree.
461 .Bl -tag -width TOG_COLORS
464 shows colorized output if this variable is set to a non-empty value.
465 The default color scheme can be modified by setting the environment
466 variables documented below.
467 The colors available in color schemes are
477 which maps to the terminal's default foreground color.
478 .It Ev TOG_COLOR_DIFF_MINUS
479 The color used to mark up removed lines in diffs.
480 If not set, the default value
483 .It Ev TOG_COLOR_DIFF_PLUS
484 The color used to mark up added lines in diffs.
485 If not set, the default value
488 .It Ev TOG_COLOR_DIFF_CHUNK_HEADER
489 The color used to mark up chunk header lines in diffs.
490 If not set, the default value
493 .It Ev TOG_COLOR_DIFF_META
494 The color used to mark up meta data in diffs.
495 If not set, the default value
498 .It Ev TOG_COLOR_TREE_SUBMODULE
499 The color used to mark up sobmodules tree entries.
500 If not set, the default value
503 .It Ev TOG_COLOR_TREE_SYMLINK
504 The color used to mark up symbolic link tree entries.
505 If not set, the default value
508 .It Ev TOG_COLOR_TREE_DIRECTORY
509 The color used to mark up directory tree entries.
510 If not set, the default value
513 .It Ev TOG_COLOR_TREE_EXECUTABLE
514 The color used to mark up executable file tree entries.
515 If not set, the default value
518 .It Ev TOG_COLOR_COMMIT
519 The color used to mark up commit IDs.
520 If not set, the default value
523 .It Ev TOG_COLOR_AUTHOR
524 The color used to mark up author information.
525 If not set, the default value
528 .It Ev TOG_COLOR_DATE
529 The color used to mark up date information.
530 If not set, the default value
533 .It Ev TOG_COLOR_REFS_HEADS
534 The color used to mark up references in the
537 If not set, the default value
540 .It Ev TOG_COLOR_REFS_TAGS
541 The color used to mark up references in the
544 If not set, the default value
547 .It Ev TOG_COLOR_REFS_REMOTES
548 The color used to mark up references in the
551 If not set, the default value
559 .Xr git-repository 5 ,
562 .An Stefan Sperling Aq Mt stsp@openbsd.org
563 .An Joshua Stein Aq Mt jcs@openbsd.org
