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 An arbitrary number of views may be opened simultaneously by
36 navigating the repository with
37 .Nm .
38 Sometimes, if one view is opened from another view, the child view
39 is linked to its parent view and both views will keep their data
40 display in sync.
41 The supported views are:
42 .Bl -tag -width Ds
43 .It Cm log view
44 Displays commits in the repository's history.
45 This view is displayed initially if no
46 .Ar command
47 is specified.
48 .It Cm diff view
49 Displays changes made in a particular commit.
50 .It Cm blame view
51 Displays the line-by-line history of a file.
52 .It Cm tree view
53 Displays the tree corresponding to a particular commit.
54 .El
55 .Pp
56 .Nm
57 provides global and command-specific key bindings and options.
58 The global key bindings are:
59 .Bl -tag -width Ds
60 .It Cm Q
61 Quit
62 .Nm .
63 .It Cm q
64 Quit the view which is in focus.
65 .It Cm Tab
66 Switch focus to the next view.
67 Cycles through all open views.
68 .It Cm Backspace
69 Switch focus to the previous view.
70 Cycles through all open views.
71 .El
72 .Pp
73 Global options must precede the command name, and are as follows:
74 .Bl -tag -width tenletters
75 .It Fl h
76 Display usage information.
77 .El
78 .Pp
79 The commands for
80 .Nm
81 are as follows:
82 .Bl -tag -width blame
83 .It Cm log [ Fl c Ar commit ] [ Fl r Ar repository-path ] [ path ]
84 Display history of a repository.
85 If a
86 .Ar path
87 is specified, show only commits which modified this path.
88 .Pp
89 This command is also executed if no explicit command is specified.
90 .Pp
91 The key bindings for
92 .Cm tog log
93 are as follows:
94 .Bl -tag -width Ds
95 .It Cm Down-arrow, j, ], Page-down
96 Move the selection cursor down.
97 .It Cm Up-arrow, k, [, Page-up
98 Move the selection cursor up.
99 .It Cm Enter
100 Switch to the
101 .Cm diff
102 view showing file changes made in the currently selected commit.
103 The diff view is linked to the log view so either view will be
104 updated when the other switches to a different commit.
105 .It Cm t
106 Switch to the
107 .Cm tree
108 view showing the tree for the currently selected commit.
109 .El
110 .Pp
111 The options for
112 .Cm tog log
113 are as follows:
114 .Bl -tag -width Ds
115 .It Fl c Ar commit
116 Start traversing history at the specified
117 .Ar commit .
118 The expected argument is the name of a branch or a SHA1 hash which corresponds
119 to a commit object.
120 .It Fl r Ar repository-path
121 Use the repository at the specified path.
122 If not specified, assume the repository is located at or above the current
123 working directory.
124 .El
125 .It Cm diff [ Ar repository-path ] Ar object1 Ar object2
126 Display the differences between two objects in the repository.
127 Each
128 .Ar object
129 argument is a SHA1 hash which corresponds to the object.
130 Both objects must be of the same type (blobs, trees, or commits).
131 If the
132 .Ar repository path
133 is omitted, use the current working directory.
134 .Pp
135 The key bindings for
136 .Cm tog diff
137 are as follows:
138 .Bl -tag -width Ds
139 .It Cm Down-arrow, j, Page-down, Space
140 Scroll down.
141 .It Cm Up-arrow, k, Page-up
142 Scroll up.
143 .It [
144 Switch to the previous commit in parent
145 .Cm log view .
146 .It ]
147 Switch to the next commit in parent
148 .Cm log view .
149 .El
150 .It Cm blame [ Fl c Ar commit ] [ Fl r Ar repository-path ] Ar path
151 Display line-by-line history of a file at the specified path.
152 .Pp
153 The key bindings for
154 .Cm tog blame
155 are as follows:
156 .Bl -tag -width Ds
157 .It Cm Down-arrow, j, Page-down, Space
158 Move the selection cursor down.
159 .It Cm Up-arrow, k, Page-up
160 Move the selection cursor up.
161 .It Cm Enter
162 Switch to the
163 .Cm diff
164 view for the currently selected line's commit.
165 .It Cm b
166 Show the
167 .Cm blame
168 view for the version of the file in the currently selected line's commit.
169 .It Cm p
170 Show the
171 .Cm blame
172 view for the version of the file in the currently selected line's commit's
173 parent commit.
174 .It Cm B
175 Switch the
176 .Cm blame
177 view back to the previously blamed commit.
178 .El
179 .Pp
180 The options for
181 .Cm tog blame
182 are as follows:
183 .Bl -tag -width Ds
184 .It Fl c Ar commit
185 Start traversing history at the specified
186 .Ar commit .
187 The expected argument is the name of a branch or a SHA1 hash which corresponds
188 to a commit object.
189 .It Fl r Ar repository-path
190 Use the repository at the specified path.
191 If not specified, assume the repository is located at or above the current
192 working directory.
193 .El
194 .It Cm tree [ Fl c Ar commit ] [ Ar repository-path ]
195 Display the repository tree.
196 If the
197 .Ar repository path
198 is omitted, assume the repository is located in the current working directory.
199 .Pp
200 The key bindings for
201 .Cm tog tree
202 are as follows:
203 .Bl -tag -width Ds
204 .It Cm Down-arrow, j, Page-down
205 Move the selection cursor down.
206 .It Cm Up-arrow, k, Page-up
207 Move the selection cursor up.
208 .It Cm Enter
209 Enter the currently selected directory, or switch to the
210 .Cm blame
211 view for the currently selected file.
212 .It Cm l
213 Switch to the
214 .Cm log
215 view for the currently selected tree entry.
216 .It Cm Left-arrow
217 Move back to the parent directory.
218 .It Cm i
219 Show the object IDs for all objects displayed in the
220 .Cm tree
221 view.
222 .El
223 .Pp
224 The options for
225 .Cm tog tree
226 are as follows:
227 .Bl -tag -width Ds
228 .It Fl c Ar commit
229 Start traversing history at the specified
230 .Ar commit .
231 The expected argument is the name of a branch or a SHA1 hash which corresponds
232 to a commit object.
233 .El
234 .El
235 .Sh EXIT STATUS
236 .Ex -std tog
237 .Sh SEE ALSO
238 .Xr git-repository 5
239 .Sh AUTHORS
240 .An Stefan Sperling Aq Mt stsp@openbsd.org