1 /*
2 * Copyright (C) 2010, Christian Halstrick <christian.halstrick@sap.com>
3 * and other copyright owners as documented in the project's IP log.
4 *
5 * This program and the accompanying materials are made available
6 * under the terms of the Eclipse Distribution License v1.0 which
7 * accompanies this distribution, is reproduced below, and is
8 * available at http://www.eclipse.org/org/documents/edl-v10.php
9 *
10 * All rights reserved.
11 *
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
14 * conditions are met:
15 *
16 * - Redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the following disclaimer.
18 *
19 * - Redistributions in binary form must reproduce the above
20 * copyright notice, this list of conditions and the following
21 * disclaimer in the documentation and/or other materials provided
22 * with the distribution.
23 *
24 * - Neither the name of the Eclipse Foundation, Inc. nor the
25 * names of its contributors may be used to endorse or promote
26 * products derived from this software without specific prior
27 * written permission.
28 *
29 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
30 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
31 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
32 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
33 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
34 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
35 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
36 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
37 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
38 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
39 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
40 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
41 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42 */
43 package org.eclipse.jgit.api;
44
45 import java.io.IOException;
46 import java.text.MessageFormat;
47 import java.util.ArrayList;
48 import java.util.List;
49
50 import org.eclipse.jgit.api.errors.GitAPIException;
51 import org.eclipse.jgit.api.errors.JGitInternalException;
52 import org.eclipse.jgit.api.errors.NoHeadException;
53 import org.eclipse.jgit.errors.IncorrectObjectTypeException;
54 import org.eclipse.jgit.errors.MissingObjectException;
55 import org.eclipse.jgit.internal.JGitText;
56 import org.eclipse.jgit.lib.AnyObjectId;
57 import org.eclipse.jgit.lib.Constants;
58 import org.eclipse.jgit.lib.ObjectId;
59 import org.eclipse.jgit.lib.Ref;
60 import org.eclipse.jgit.lib.Repository;
61 import org.eclipse.jgit.revwalk.RevCommit;
62 import org.eclipse.jgit.revwalk.RevWalk;
63 import org.eclipse.jgit.revwalk.filter.AndRevFilter;
64 import org.eclipse.jgit.revwalk.filter.MaxCountRevFilter;
65 import org.eclipse.jgit.revwalk.filter.RevFilter;
66 import org.eclipse.jgit.revwalk.filter.SkipRevFilter;
67 import org.eclipse.jgit.treewalk.filter.AndTreeFilter;
68 import org.eclipse.jgit.treewalk.filter.PathFilter;
69 import org.eclipse.jgit.treewalk.filter.PathFilterGroup;
70 import org.eclipse.jgit.treewalk.filter.TreeFilter;
71
72 /**
73 * A class used to execute a {@code Log} command. It has setters for all
74 * supported options and arguments of this command and a {@link #call()} method
75 * to finally execute the command. Each instance of this class should only be
76 * used for one invocation of the command (means: one call to {@link #call()})
77 * <p>
78 * Examples (<code>git</code> is a {@link org.eclipse.jgit.api.Git} instance):
79 * <p>
80 * Get newest 10 commits, starting from the current branch:
81 *
82 * <pre>
83 * ObjectId head = repository.resolve(Constants.HEAD);
84 *
85 * Iterable<RevCommit> commits = git.log().add(head).setMaxCount(10).call();
86 * </pre>
87 * <p>
88 *
89 * <p>
90 * Get commits only for a specific file:
91 *
92 * <pre>
93 * git.log().add(head).addPath("dir/filename.txt").call();
94 * </pre>
95 * <p>
96 *
97 * @see <a href="http://www.kernel.org/pub/software/scm/git/docs/git-log.html"
98 * >Git documentation about Log</a>
99 */
100 public class LogCommand extends GitCommand<Iterable<RevCommit>> {
101 private RevWalk walk;
102
103 private boolean startSpecified = false;
104
105 private RevFilter revFilter;
106
107 private final List<PathFilter> pathFilters = new ArrayList<>();
108
109 private int maxCount = -1;
110
111 private int skip = -1;
112
113 /**
114 * Constructor for LogCommand.
115 *
116 * @param repo
117 * the {@link org.eclipse.jgit.lib.Repository}
118 */
119 protected LogCommand(Repository repo) {
120 super(repo);
121 walk = new RevWalk(repo);
122 }
123
124 /**
125 * {@inheritDoc}
126 * <p>
127 * Executes the {@code Log} command with all the options and parameters
128 * collected by the setter methods (e.g. {@link #add(AnyObjectId)},
129 * {@link #not(AnyObjectId)}, ..) of this class. Each instance of this class
130 * should only be used for one invocation of the command. Don't call this
131 * method twice on an instance.
132 */
133 @Override
134 public Iterable<RevCommit> call() throws GitAPIException, NoHeadException {
135 checkCallable();
136 if (!pathFilters.isEmpty())
137 walk.setTreeFilter(AndTreeFilter.create(
138 PathFilterGroup.create(pathFilters), TreeFilter.ANY_DIFF));
139 if (skip > -1 && maxCount > -1)
140 walk.setRevFilter(AndRevFilter.create(SkipRevFilter.create(skip),
141 MaxCountRevFilter.create(maxCount)));
142 else if (skip > -1)
143 walk.setRevFilter(SkipRevFilter.create(skip));
144 else if (maxCount > -1)
145 walk.setRevFilter(MaxCountRevFilter.create(maxCount));
146 if (!startSpecified) {
147 try {
148 ObjectId headId = repo.resolve(Constants.HEAD);
149 if (headId == null)
150 throw new NoHeadException(
151 JGitText.get().noHEADExistsAndNoExplicitStartingRevisionWasSpecified);
152 add(headId);
153 } catch (IOException e) {
154 // all exceptions thrown by add() shouldn't occur and represent
155 // severe low-level exception which are therefore wrapped
156 throw new JGitInternalException(
157 JGitText.get().anExceptionOccurredWhileTryingToAddTheIdOfHEAD,
158 e);
159 }
160 }
161
162 if (this.revFilter != null) {
163 walk.setRevFilter(this.revFilter);
164 }
165
166 setCallable(false);
167 return walk;
168 }
169
170 /**
171 * Mark a commit to start graph traversal from.
172 *
173 * @see RevWalk#markStart(RevCommit)
174 * @param start
175 * the id of the commit to start from
176 * @return {@code this}
177 * @throws org.eclipse.jgit.errors.MissingObjectException
178 * the commit supplied is not available from the object
179 * database. This usually indicates the supplied commit is
180 * invalid, but the reference was constructed during an earlier
181 * invocation to
182 * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}.
183 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
184 * the object was not parsed yet and it was discovered during
185 * parsing that it is not actually a commit. This usually
186 * indicates the caller supplied a non-commit SHA-1 to
187 * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}.
188 * @throws JGitInternalException
189 * a low-level exception of JGit has occurred. The original
190 * exception can be retrieved by calling
191 * {@link java.lang.Exception#getCause()}. Expect only
192 * {@code IOException's} to be wrapped. Subclasses of
193 * {@link java.io.IOException} (e.g.
194 * {@link org.eclipse.jgit.errors.MissingObjectException}) are
195 * typically not wrapped here but thrown as original exception
196 */
197 public LogCommand add(AnyObjectId start) throws MissingObjectException,
198 IncorrectObjectTypeException {
199 return add(true, start);
200 }
201
202 /**
203 * Same as {@code --not start}, or {@code ^start}
204 *
205 * @param start
206 * a {@link org.eclipse.jgit.lib.AnyObjectId}
207 * @return {@code this}
208 * @throws org.eclipse.jgit.errors.MissingObjectException
209 * the commit supplied is not available from the object
210 * database. This usually indicates the supplied commit is
211 * invalid, but the reference was constructed during an earlier
212 * invocation to
213 * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}.
214 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
215 * the object was not parsed yet and it was discovered during
216 * parsing that it is not actually a commit. This usually
217 * indicates the caller supplied a non-commit SHA-1 to
218 * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}.
219 * @throws JGitInternalException
220 * a low-level exception of JGit has occurred. The original
221 * exception can be retrieved by calling
222 * {@link java.lang.Exception#getCause()}. Expect only
223 * {@code IOException's} to be wrapped. Subclasses of
224 * {@link java.io.IOException} (e.g.
225 * {@link org.eclipse.jgit.errors.MissingObjectException}) are
226 * typically not wrapped here but thrown as original exception
227 */
228 public LogCommand not(AnyObjectId start) throws MissingObjectException,
229 IncorrectObjectTypeException {
230 return add(false, start);
231 }
232
233 /**
234 * Adds the range {@code since..until}
235 *
236 * @param since
237 * a {@link org.eclipse.jgit.lib.AnyObjectId} object.
238 * @param until
239 * a {@link org.eclipse.jgit.lib.AnyObjectId} object.
240 * @return {@code this}
241 * @throws org.eclipse.jgit.errors.MissingObjectException
242 * the commit supplied is not available from the object
243 * database. This usually indicates the supplied commit is
244 * invalid, but the reference was constructed during an earlier
245 * invocation to
246 * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}.
247 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
248 * the object was not parsed yet and it was discovered during
249 * parsing that it is not actually a commit. This usually
250 * indicates the caller supplied a non-commit SHA-1 to
251 * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}.
252 * @throws JGitInternalException
253 * a low-level exception of JGit has occurred. The original
254 * exception can be retrieved by calling
255 * {@link java.lang.Exception#getCause()}. Expect only
256 * {@code IOException's} to be wrapped. Subclasses of
257 * {@link java.io.IOException} (e.g.
258 * {@link org.eclipse.jgit.errors.MissingObjectException}) are
259 * typically not wrapped here but thrown as original exception
260 */
261 public LogCommand addRange(AnyObjectId/../../../org/eclipse/jgit/lib/AnyObjectId.html#AnyObjectId">AnyObjectId since, AnyObjectId until)
262 throws MissingObjectException, IncorrectObjectTypeException {
263 return not(since).add(until);
264 }
265
266 /**
267 * Add all refs as commits to start the graph traversal from.
268 *
269 * @see #add(AnyObjectId)
270 * @return {@code this}
271 * @throws java.io.IOException
272 * the references could not be accessed
273 */
274 public LogCommand all() throws IOException {
275 for (Ref ref : getRepository().getRefDatabase().getRefs()) {
276 if(!ref.isPeeled())
277 ref = getRepository().getRefDatabase().peel(ref);
278
279 ObjectId objectId = ref.getPeeledObjectId();
280 if (objectId == null)
281 objectId = ref.getObjectId();
282 RevCommit commit = null;
283 try {
284 commit = walk.parseCommit(objectId);
285 } catch (MissingObjectException | IncorrectObjectTypeException e) {
286 // ignore as traversal starting point:
287 // - the ref points to an object that does not exist
288 // - the ref points to an object that is not a commit (e.g. a
289 // tree or a blob)
290 }
291 if (commit != null)
292 add(commit);
293 }
294 return this;
295 }
296
297 /**
298 * Show only commits that affect any of the specified paths. The path must
299 * either name a file or a directory exactly and use <code>/</code> (slash)
300 * as separator. Note that regex expressions or wildcards are not supported.
301 *
302 * @param path
303 * a repository-relative path (with <code>/</code> as separator)
304 * @return {@code this}
305 */
306 public LogCommand addPath(String path) {
307 checkCallable();
308 pathFilters.add(PathFilter.create(path));
309 return this;
310 }
311
312 /**
313 * Skip the number of commits before starting to show the commit output.
314 *
315 * @param skip
316 * the number of commits to skip
317 * @return {@code this}
318 */
319 public LogCommand setSkip(int skip) {
320 checkCallable();
321 this.skip = skip;
322 return this;
323 }
324
325 /**
326 * Limit the number of commits to output.
327 *
328 * @param maxCount
329 * the limit
330 * @return {@code this}
331 */
332 public LogCommand setMaxCount(int maxCount) {
333 checkCallable();
334 this.maxCount = maxCount;
335 return this;
336 }
337
338 private LogCommand add(boolean include, AnyObjectId start)
339 throws MissingObjectException, IncorrectObjectTypeException,
340 JGitInternalException {
341 checkCallable();
342 try {
343 if (include) {
344 walk.markStart(walk.lookupCommit(start));
345 startSpecified = true;
346 } else
347 walk.markUninteresting(walk.lookupCommit(start));
348 return this;
349 } catch (MissingObjectException | IncorrectObjectTypeException e) {
350 throw e;
351 } catch (IOException e) {
352 throw new JGitInternalException(MessageFormat.format(
353 JGitText.get().exceptionOccurredDuringAddingOfOptionToALogCommand
354 , start), e);
355 }
356 }
357
358
359 /**
360 * Set a filter for the <code>LogCommand</code>.
361 *
362 * @param aFilter
363 * the filter that this instance of <code>LogCommand</code>
364 * should use
365 * @return {@code this}
366 * @since 4.4
367 */
368 public LogCommand setRevFilter(RevFilter aFilter) {
369 checkCallable();
370 this.revFilter = aFilter;
371 return this;
372 }
373 }