1 .\"
2 .\" Copyright (c) 2018 Stefan Sperling
3 .\"
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.
7 .\"
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.
15 .\"
16 .Dd $Mdocdate$
17 .Dt TOG 1
18 .Os
19 .Sh NAME
20 .Nm tog
21 .Nd git repository browser
22 .Sh SYNOPSIS
23 .Nm
24 .Ar command
25 .Op Fl h
26 .Op Ar arg ...
27 .Sh DESCRIPTION
28 .Nm
29 is an interactive read-only browser for git repositories.
30 This repository format is described in
31 .Xr git-repository 5 .
32 .Pp
33 .Nm
34 supports several types of views which display repository data:
35 .Bl -tag -width Ds
36 .It Cm log view
37 Displays commits in the repository's history.
38 This view is displayed initially if no
39 .Ar command
40 is specified.
41 .It Cm diff view
42 Displays changes made in a particular commit.
43 .It Cm blame view
44 Displays the line-by-line history of a file.
45 .It Cm tree view
46 Displays the tree corresponding to a particular commit.
47 .El
48 .Pp
49 .Nm
50 provides global and command-specific key bindings and options.
51 The global key bindings are:
52 .Bl -tag -width Ds
53 .It Cm Q
54 Quit
55 .Nm .
56 .It Cm q
57 Quit the view which is in focus.
58 .It Cm Tab
59 Switch focus to the next view. Cycles through all views.
60 .It Cm ~
61 Switch focus to the previous view. Cycles through all views.
62 .It Cm f
63 Toggle fullscreen mode for the view which is in focus.
64 .El
65 .Pp
66 Global options must precede the command name, and are as follows:
67 .Bl -tag -width tenletters
68 .It Fl h
69 Display usage information.
70 .El
71 .Pp
72 The commands for
73 .Nm
74 are as follows:
75 .Bl -tag -width blame
76 .It Cm log [ Fl c Ar commit ] [ Fl r Ar repository-path ] [ path ]
77 Display history of a repository.
78 If a
79 .Ar path
80 is specified, show only commits which modified this path.
81 .Pp
82 This command is also executed if no explicit command is specified.
83 .Pp
84 The key bindings for
85 .Cm tog log
86 are as follows:
87 .Bl -tag -width Ds
88 .It Cm Down-arrow, j, ], Page-down
89 Move the selection cursor down.
90 .It Cm Up-arrow, k, [, Page-up
91 Move the selection cursor up.
92 .It Cm Enter
93 Switch to the
94 .Cm diff
95 view showing file changes made in the currently selected commit.
96 .It Cm t
97 Switch to the
98 .Cm tree
99 view showing the tree for the currently selected commit.
100 .It Cm Backspace
101 Show log entries for the parent directory of the currently selected path.
102 .El
103 .Pp
104 The options for
105 .Cm tog log
106 are as follows:
107 .Bl -tag -width Ds
108 .It Fl c Ar commit
109 Start traversing history at the specified
110 .Ar commit .
111 The expected argument is the name of a branch or a SHA1 hash which corresponds
112 to a commit object.
113 .It Fl r Ar repository-path
114 Use the repository at the specified path.
115 If not specified, assume the repository is located at or above the current
116 working directory.
117 .El
118 .It Cm diff [ Ar repository-path ] Ar object1 Ar object2
119 Display the differences between two objects in the repository.
120 Each
121 .Ar object
122 argument is a SHA1 hash which corresponds to the object.
123 Both objects must be of the same type (blobs, trees, or commits).
124 If the
125 .Ar repository path
126 is omitted, use the current working directory.
127 .Pp
128 The key bindings for
129 .Cm tog diff
130 are as follows:
131 .Bl -tag -width Ds
132 .It Cm Down-arrow, j, Page-down, Space
133 Scroll down.
134 .It Cm Up-arrow, k, Page-up
135 Scroll up.
136 .El
137 .It Cm blame [ Fl c Ar commit ] [ Fl r Ar repository-path ] Ar path
138 Display line-by-line history of a file at the specified path.
139 .Pp
140 The key bindings for
141 .Cm tog blame
142 are as follows:
143 .Bl -tag -width Ds
144 .It Cm Down-arrow, j, Page-down, Space
145 Move the selection cursor down.
146 .It Cm Up-arrow, k, Page-up
147 Move the selection cursor up.
148 .It Cm Enter
149 Switch to the
150 .Cm diff
151 view for the currently selected line's commit.
152 .It Cm b
153 Show the
154 .Cm blame
155 view for the version of the file in the currently selected line's commit.
156 .It Cm p
157 Show the
158 .Cm blame
159 view for the version of the file in the currently selected line's commit's
160 parent commit.
161 .It Cm B
162 Switch the
163 .Cm blame
164 view back to the previously blamed commit.
165 .El
166 .Pp
167 The options for
168 .Cm tog blame
169 are as follows:
170 .Bl -tag -width Ds
171 .It Fl c Ar commit
172 Start traversing history at the specified
173 .Ar commit .
174 The expected argument is the name of a branch or a SHA1 hash which corresponds
175 to a commit object.
176 .It Fl r Ar repository-path
177 Use the repository at the specified path.
178 If not specified, assume the repository is located at or above the current
179 working directory.
180 .El
181 .It Cm tree [ Fl c Ar commit ] [ Ar repository-path ]
182 Display the repository tree.
183 If the
184 .Ar repository path
185 is omitted, assume the repository is located in the current working directory.
186 .Pp
187 The key bindings for
188 .Cm tog tree
189 are as follows:
190 .Bl -tag -width Ds
191 .It Cm Down-arrow, j, Page-down
192 Move the selection cursor down.
193 .It Cm Up-arrow, k, Page-up
194 Move the selection cursor up.
195 .It Cm Enter
196 Enter the currently selected directory, or switch to the
197 .Cm blame
198 view for the currently selected file.
199 .It Cm l
200 Switch to the
201 .Cm log
202 view for the currently selected tree entry.
203 .It Cm Backspace
204 Move back to the parent directory.
205 .It Cm i
206 Show the object IDs for all objects displayed in the
207 .Cm tree
208 view.
209 .El
210 .Pp
211 The options for
212 .Cm tog tree
213 are as follows:
214 .Bl -tag -width Ds
215 .It Fl c Ar commit
216 Start traversing history at the specified
217 .Ar commit .
218 The expected argument is the name of a branch or a SHA1 hash which corresponds
219 to a commit object.
220 .El
221 .El
222 .Sh EXIT STATUS
223 .Ex -std tog
224 .Sh SEE ALSO
225 .Xr git-repository 5
226 .Sh AUTHORS
227 .An Stefan Sperling Aq Mt stsp@openbsd.org