org.eclipse.jgit.revwalk

## Class RevWalk

- java.lang.Object
- - org.eclipse.jgit.revwalk.RevWalk

All Implemented Interfaces:
  Iterable<RevCommit>

Direct Known Subclasses:
  DepthWalk.RevWalk, ObjectWalk, PlotWalk

    public class RevWalk
    extends Object
    implements Iterable<RevCommit>

Walks a commit graph and produces the matching commits in order.

A RevWalk instance can only be used once to generate results. Running a second time requires creating a new RevWalk instance, or invoking `reset()` before starting again. Resetting an existing instance may be faster for some applications as commit body parsing can be avoided on the later invocations.

RevWalk instances are not thread-safe. Applications must either restrict usage of a RevWalk instance to a single thread, or implement their own synchronization at a higher level.

Multiple simultaneous RevWalk instances per `Repository` are permitted, even from concurrent threads. Equality of `RevCommit`s from two different RevWalk instances is never true, even if their `ObjectId`s are equal (and thus they describe the same commit).

The offered iterator is over the list of RevCommits described by the configuration of this instance. Applications should restrict themselves to using either the provided Iterator or `next()`, but never use both on the same RevWalk at the same time. The Iterator may buffer RevCommits, while `next()` does not.

### Constructor Summary

Constructors
Constructor and Description
`RevWalk(ObjectReader or)` Create a new revision walker for a given repository.
`RevWalk(Repository repo)` Create a new revision walker for a given repository.

### Method Summary

All Methods Instance Methods Concrete Methods
`protected void` `assertNotStarted()` Throws an exception if we have started producing output.
`void` `assumeShallow(Collection<? extends ObjectId> ids)` Assume additional commits are shallow (have no parents).
`void` `carry(Collection<RevFlag> set)` Automatically carry flags from a child commit to its parents.
`void` `carry(RevFlag flag)` Automatically carry a flag from a child commit to its parents.
`protected RevCommit` `createCommit(AnyObjectId id)` Construct a new unparsed commit for the given object.
`void` `dispose()` Dispose all internal state and invalidate all RevObject instances.
`void` `disposeFlag(RevFlag flag)` Allow a flag to be recycled for a different use.
`ObjectReader` `getObjectReader()`
`RevFilter` `getRevFilter()` Get the currently configured commit filter.
`EnumSet<RevSort>` `getRevSort()` Obtain the sort types applied to the commits returned.
`TreeFilter` `getTreeFilter()` Get the tree filter used to simplify commits by modified paths.
`boolean` `hasRevSort(RevSort sort)` Check whether the provided sorting strategy is enabled.
`boolean` `isMergedInto(RevCommit base, RevCommit tip)` Determine if a commit is reachable from another commit.
`boolean` `isRetainBody()` Should the body of a commit or tag be retained after parsing its headers?
`Iterator<RevCommit>` `iterator()` Returns an Iterator over the commits of this walker.
`RevObject` `lookupAny(AnyObjectId id, int type)` Locate a reference to any object without loading it.
`RevBlob` `lookupBlob(AnyObjectId id)` Locate a reference to a blob without loading it.
`RevCommit` `lookupCommit(AnyObjectId id)` Locate a reference to a commit without loading it.
`RevObject` `lookupOrNull(AnyObjectId id)` Locate an object that was previously allocated in this walk.
`RevTag` `lookupTag(AnyObjectId id)` Locate a reference to a tag without loading it.
`RevTree` `lookupTree(AnyObjectId id)` Locate a reference to a tree without loading it.
`void` `markStart(Collection<RevCommit> list)` Mark commits to start graph traversal from.
`void` `markStart(RevCommit c)` Mark a commit to start graph traversal from.
`void` `markUninteresting(RevCommit c)` Mark a commit to not produce in the output.
`RevFlag` `newFlag(String name)` Create a new flag for application use during walking.
`RevCommit` `next()` Pop the next most recent commit.
`RevObject` `parseAny(AnyObjectId id)` Locate a reference to any object and immediately parse its headers.
`<T extends ObjectId> AsyncRevObjectQueue` `parseAny(Iterable<T> objectIds, boolean reportMissing)` Asynchronous object parsing.
`void` `parseBody(RevObject obj)` Ensure the object's full body content is available.
`RevCommit` `parseCommit(AnyObjectId id)` Locate a reference to a commit and immediately parse its content.
`void` `parseHeaders(RevObject obj)` Ensure the object's critical headers have been parsed.
`RevTag` `parseTag(AnyObjectId id)` Locate a reference to an annotated tag and immediately parse its content.
`RevTree` `parseTree(AnyObjectId id)` Locate a reference to a tree.
`RevObject` `peel(RevObject obj)` Peel back annotated tags until a non-tag object is found.
`void` `release()` Release any resources used by this walker's reader.
`void` `reset()` Resets internal state and allows this instance to be used again.
`protected void` `reset(int retainFlags)` Resets internal state and allows this instance to be used again.
`void` `resetRetain(RevFlag... retainFlags)` Resets internal state and allows this instance to be used again.
`void` `resetRetain(RevFlagSet retainFlags)` Resets internal state and allows this instance to be used again.
`void` `retainOnReset(Collection<RevFlag> flags)` Preserve a set of RevFlags during all `reset` methods.
`void` `retainOnReset(RevFlag flag)` Preserve a RevFlag during all `reset` methods.
`void` `setRetainBody(boolean retain)` Set whether or not the body of a commit or tag is retained.
`void` `setRevFilter(RevFilter newFilter)` Set the commit filter for this walker.
`void` `setRewriteParents(boolean rewrite)` Set whether to rewrite parent pointers when filtering by modified paths.
`void` `setTreeFilter(TreeFilter newFilter)` Set the tree filter used to simplify commits by modified paths.
`void` `sort(RevSort s)` Select a single sorting strategy for the returned commits.
`void` `sort(RevSort s, boolean use)` Add or remove a sorting strategy for the returned commits.
`ObjectWalk` `toObjectWalkWithSameObjects()` Create and return an `ObjectWalk` using the same objects.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

### Constructor Detail

#### RevWalk

    public RevWalk(Repository repo)

Create a new revision walker for a given repository.

Parameters:
  `repo` - the repository the walker will obtain data from. An ObjectReader will be created by the walker, and must be released by the caller.

#### RevWalk

    public RevWalk(ObjectReader or)

Create a new revision walker for a given repository.

Parameters:
  `or` - the reader the walker will obtain data from. The reader should be released by the caller when the walker is no longer required.

### Method Detail

#### getObjectReader

    public ObjectReader getObjectReader()

Returns:
  the reader this walker is using to load objects.

#### release

    public void release()

Release any resources used by this walker's reader.

A walker that has been released can be used again, but may need to be released after the subsequent usage.

#### markStart

    public void markStart(RevCommit c)
                   throws MissingObjectException,
                          IncorrectObjectTypeException,
                          IOException

Mark a commit to start graph traversal from.

Callers are encouraged to use `parseCommit(AnyObjectId)` to obtain the commit reference, rather than `lookupCommit(AnyObjectId)`, as this method requires the commit to be parsed before it can be added as a root for the traversal.

The method will automatically parse an unparsed commit, but error handling may be more difficult for the application to explain why a RevCommit is not actually a commit. The object pool of this walker would also be 'poisoned' by the non-commit RevCommit.

Parameters:
  `c` - the commit to start traversing from. The commit passed must be from this same revision walker.
Throws:
  `MissingObjectException` - the commit supplied is not available from the object database. This usually indicates the supplied commit is invalid, but the reference was constructed during an earlier invocation to `lookupCommit(AnyObjectId)`.
  `IncorrectObjectTypeException` - the object was not parsed yet and it was discovered during parsing that it is not actually a commit. This usually indicates the caller supplied a non-commit SHA-1 to `lookupCommit(AnyObjectId)`.
  `IOException` - a pack file or loose object could not be read.

#### markStart

    public void markStart(Collection<RevCommit> list)
                   throws MissingObjectException,
                          IncorrectObjectTypeException,
                          IOException

Mark commits to start graph traversal from.

Parameters:
  `list` - commits to start traversing from. The commits passed must be from this same revision walker.
Throws:
  `MissingObjectException` - one of the commits supplied is not available from the object database. This usually indicates the supplied commit is invalid, but the reference was constructed during an earlier invocation to `lookupCommit(AnyObjectId)`.
  `IncorrectObjectTypeException` - the object was not parsed yet and it was discovered during parsing that it is not actually a commit. This usually indicates the caller supplied a non-commit SHA-1 to `lookupCommit(AnyObjectId)`.
  `IOException` - a pack file or loose object could not be read.

#### markUninteresting

    public void markUninteresting(RevCommit c)
                           throws MissingObjectException,
                                  IncorrectObjectTypeException,
                                  IOException

Mark a commit to not produce in the output.

Uninteresting commits denote not just themselves but also their entire ancestry chain, back until the merge base of an uninteresting commit and an otherwise interesting commit.

Callers are encouraged to use `parseCommit(AnyObjectId)` to obtain the commit reference, rather than `lookupCommit(AnyObjectId)`, as this method requires the commit to be parsed before it can be added as a root for the traversal.

The method will automatically parse an unparsed commit, but error handling may be more difficult for the application to explain why a RevCommit is not actually a commit. The object pool of this walker would also be 'poisoned' by the non-commit RevCommit.

Parameters:
  `c` - the commit to start traversing from. The commit passed must be from this same revision walker.
Throws:
  `MissingObjectException` - the commit supplied is not available from the object database. This usually indicates the supplied commit is invalid, but the reference was constructed during an earlier invocation to `lookupCommit(AnyObjectId)`.
  `IncorrectObjectTypeException` - the object was not parsed yet and it was discovered during parsing that it is not actually a commit. This usually indicates the caller supplied a non-commit SHA-1 to `lookupCommit(AnyObjectId)`.
  `IOException` - a pack file or loose object could not be read.

#### isMergedInto

    public boolean isMergedInto(RevCommit base,
                                RevCommit tip)
                         throws MissingObjectException,
                                IncorrectObjectTypeException,
                                IOException

Determine if a commit is reachable from another commit.

A commit `base` is an ancestor of `tip` if we can find a path of commits that leads from `tip` and ends at `base`.

This utility function resets the walker, inserts the two supplied commits, and then executes a walk until an answer can be obtained. Currently allocated RevFlags that have been added to RevCommit instances will be retained through the reset.

Parameters:
  `base` - commit the caller thinks is reachable from `tip`.
  `tip` - commit to start iteration from, and which is most likely a descendant (child) of `base`.
Returns:
  true if there is a path directly from `tip` to `base` (and thus `base` is fully merged into `tip`); false otherwise.
Throws:
  `MissingObjectException` - one or or more of the next commit's parents are not available from the object database, but were thought to be candidates for traversal. This usually indicates a broken link.
  `IncorrectObjectTypeException` - one or or more of the next commit's parents are not actually commit objects.
  `IOException` - a pack file or loose object could not be read.

#### next

    public RevCommit next()
                   throws MissingObjectException,
                          IncorrectObjectTypeException,
                          IOException

Pop the next most recent commit.

Returns:
  next most recent commit; null if traversal is over.
Throws:
  `MissingObjectException` - one or or more of the next commit's parents are not available from the object database, but were thought to be candidates for traversal. This usually indicates a broken link.
  `IncorrectObjectTypeException` - one or or more of the next commit's parents are not actually commit objects.
  `IOException` - a pack file or loose object could not be read.

#### getRevSort

    public EnumSet<RevSort> getRevSort()

Obtain the sort types applied to the commits returned.

Returns:
  the sorting strategies employed. At least one strategy is always used, but that strategy may be `RevSort.NONE`.

#### hasRevSort

    public boolean hasRevSort(RevSort sort)

Check whether the provided sorting strategy is enabled.

Parameters:
  `sort` - a sorting strategy to look for.
Returns:
  true if this strategy is enabled, false otherwise

#### sort

    public void sort(RevSort s)

Select a single sorting strategy for the returned commits.

Disables all sorting strategies, then enables only the single strategy supplied by the caller.

Parameters:
  `s` - a sorting strategy to enable.

#### sort

    public void sort(RevSort s,
                     boolean use)

Add or remove a sorting strategy for the returned commits.

Multiple strategies can be applied at once, in which case some strategies may take precedence over others. As an example, `RevSort.TOPO` must take precedence over `RevSort.COMMIT_TIME_DESC`, otherwise it cannot enforce its ordering.

Parameters:
  `s` - a sorting strategy to enable or disable.
  `use` - true if this strategy should be used, false if it should be removed.

#### getRevFilter

    public RevFilter getRevFilter()

Get the currently configured commit filter.

Returns:
  the current filter. Never null as a filter is always needed.

#### setRevFilter

    public void setRevFilter(RevFilter newFilter)

Set the commit filter for this walker.

Multiple filters may be combined by constructing an arbitrary tree of `AndRevFilter` or `OrRevFilter` instances to describe the boolean expression required by the application. Custom filter implementations may also be constructed by applications.

Note that filters are not thread-safe and may not be shared by concurrent RevWalk instances. Every RevWalk must be supplied its own unique filter, unless the filter implementation specifically states it is (and always will be) thread-safe. Callers may use `RevFilter.clone()` to create a unique filter tree for this RevWalk instance.

Parameters:
  `newFilter` - the new filter. If null the special `RevFilter.ALL` filter will be used instead, as it matches every commit.
See Also:
  `AndRevFilter`, `OrRevFilter`

#### getTreeFilter

    public TreeFilter getTreeFilter()

Get the tree filter used to simplify commits by modified paths.

Returns:
  the current filter. Never null as a filter is always needed. If no filter is being applied `TreeFilter.ALL` is returned.

#### setTreeFilter

    public void setTreeFilter(TreeFilter newFilter)

Set the tree filter used to simplify commits by modified paths.

If null or `TreeFilter.ALL` the path limiter is removed. Commits will not be simplified.

If non-null and not `TreeFilter.ALL` then the tree filter will be installed. Commits will have their ancestry simplified to hide commits that do not contain tree entries matched by the filter, unless `setRewriteParents(false)` is called.

Usually callers should be inserting a filter graph including `TreeFilter.ANY_DIFF` along with one or more `PathFilter` instances.

Parameters:
  `newFilter` - new filter. If null the special `TreeFilter.ALL` filter will be used instead, as it matches everything.
See Also:
  `PathFilter`

#### setRewriteParents

    public void setRewriteParents(boolean rewrite)

Set whether to rewrite parent pointers when filtering by modified paths.

By default, when `setTreeFilter(TreeFilter)` is called with non- null and non-`TreeFilter.ALL` filter, commits will have their ancestry simplified and parents rewritten to hide commits that do not match the filter.

This behavior can be bypassed by passing false to this method.

Parameters:
  `rewrite` - whether to rewrite parents; defaults to true.
Since:
  3.4

#### isRetainBody

    public boolean isRetainBody()

Should the body of a commit or tag be retained after parsing its headers?

Usually the body is always retained, but some application code might not care and would prefer to discard the body of a commit as early as possible, to reduce memory usage.

Returns:
  true if the body should be retained; false it is discarded.

#### setRetainBody

    public void setRetainBody(boolean retain)

Set whether or not the body of a commit or tag is retained.

If a body of a commit or tag is not retained, the application must call `parseBody(RevObject)` before the body can be safely accessed through the type specific access methods.

Parameters:
  `retain` - true to retain bodies; false to discard them early.

#### lookupBlob

    public RevBlob lookupBlob(AnyObjectId id)

Locate a reference to a blob without loading it.

The blob may or may not exist in the repository. It is impossible to tell from this method's return value.

Parameters:
  `id` - name of the blob object.
Returns:
  reference to the blob object. Never null.

#### lookupTree

    public RevTree lookupTree(AnyObjectId id)

Locate a reference to a tree without loading it.

The tree may or may not exist in the repository. It is impossible to tell from this method's return value.

Parameters:
  `id` - name of the tree object.
Returns:
  reference to the tree object. Never null.

#### lookupCommit

    public RevCommit lookupCommit(AnyObjectId id)

Locate a reference to a commit without loading it.

The commit may or may not exist in the repository. It is impossible to tell from this method's return value.

See `parseHeaders(RevObject)` and `parseBody(RevObject)` for loading contents.

Parameters:
  `id` - name of the commit object.
Returns:
  reference to the commit object. Never null.

#### lookupTag

    public RevTag lookupTag(AnyObjectId id)

Locate a reference to a tag without loading it.

The tag may or may not exist in the repository. It is impossible to tell from this method's return value.

Parameters:
  `id` - name of the tag object.
Returns:
  reference to the tag object. Never null.

#### lookupAny

    public RevObject lookupAny(AnyObjectId id,
                               int type)

Locate a reference to any object without loading it.

The object may or may not exist in the repository. It is impossible to tell from this method's return value.

Parameters:
  `id` - name of the object.
  `type` - type of the object. Must be a valid Git object type.
Returns:
  reference to the object. Never null.

#### lookupOrNull

    public RevObject lookupOrNull(AnyObjectId id)

Locate an object that was previously allocated in this walk.

Parameters:
  `id` - name of the object.
Returns:
  reference to the object if it has been previously located; otherwise null.

#### parseCommit

    public RevCommit parseCommit(AnyObjectId id)
                          throws MissingObjectException,
                                 IncorrectObjectTypeException,
                                 IOException

Locate a reference to a commit and immediately parse its content.

Unlike `lookupCommit(AnyObjectId)` this method only returns successfully if the commit object exists, is verified to be a commit, and was parsed without error.

Parameters:
  `id` - name of the commit object.
Returns:
  reference to the commit object. Never null.
Throws:
  `MissingObjectException` - the supplied commit does not exist.
  `IncorrectObjectTypeException` - the supplied id is not a commit or an annotated tag.
  `IOException` - a pack file or loose object could not be read.

#### parseTree

    public RevTree parseTree(AnyObjectId id)
                      throws MissingObjectException,
                             IncorrectObjectTypeException,
                             IOException

Locate a reference to a tree.

This method only returns successfully if the tree object exists, is verified to be a tree.

Parameters:
  `id` - name of the tree object, or a commit or annotated tag that may reference a tree.
Returns:
  reference to the tree object. Never null.
Throws:
  `MissingObjectException` - the supplied tree does not exist.
  `IncorrectObjectTypeException` - the supplied id is not a tree, a commit or an annotated tag.
  `IOException` - a pack file or loose object could not be read.

#### parseTag

    public RevTag parseTag(AnyObjectId id)
                    throws MissingObjectException,
                           IncorrectObjectTypeException,
                           IOException

Locate a reference to an annotated tag and immediately parse its content.

Unlike `lookupTag(AnyObjectId)` this method only returns successfully if the tag object exists, is verified to be a tag, and was parsed without error.

Parameters:
  `id` - name of the tag object.
Returns:
  reference to the tag object. Never null.
Throws:
  `MissingObjectException` - the supplied tag does not exist.
  `IncorrectObjectTypeException` - the supplied id is not a tag or an annotated tag.
  `IOException` - a pack file or loose object could not be read.

#### parseAny

    public RevObject parseAny(AnyObjectId id)
                       throws MissingObjectException,
                              IOException

Locate a reference to any object and immediately parse its headers.

This method only returns successfully if the object exists and was parsed without error. Parsing an object can be expensive as the type must be determined. For blobs this may mean the blob content was unpacked unnecessarily, and thrown away.

Parameters:
  `id` - name of the object.
Returns:
  reference to the object. Never null.
Throws:
  `MissingObjectException` - the supplied does not exist.
  `IOException` - a pack file or loose object could not be read.

#### parseAny

    public <T extends ObjectId> AsyncRevObjectQueue parseAny(Iterable<T> objectIds,
                                                             boolean reportMissing)

Asynchronous object parsing.

Type Parameters:
  `T` - any ObjectId type.
Parameters:
  `objectIds` - objects to open from the object store. The supplied collection must not be modified until the queue has finished.
  `reportMissing` - if true missing objects are reported by calling failure with a MissingObjectException. This may be more expensive for the implementation to guarantee. If false the implementation may choose to report MissingObjectException, or silently skip over the object with no warning.
Returns:
  queue to read the objects from.

#### parseHeaders

    public void parseHeaders(RevObject obj)
                      throws MissingObjectException,
                             IOException

Ensure the object's critical headers have been parsed.

This method only returns successfully if the object exists and was parsed without error.

Parameters:
  `obj` - the object the caller needs to be parsed.
Throws:
  `MissingObjectException` - the supplied does not exist.
  `IOException` - a pack file or loose object could not be read.

#### parseBody

    public void parseBody(RevObject obj)
                   throws MissingObjectException,
                          IOException

Ensure the object's full body content is available.

This method only returns successfully if the object exists and was parsed without error.

Parameters:
  `obj` - the object the caller needs to be parsed.
Throws:
  `MissingObjectException` - the supplied does not exist.
  `IOException` - a pack file or loose object could not be read.

#### peel

    public RevObject peel(RevObject obj)
                   throws MissingObjectException,
                          IOException

Peel back annotated tags until a non-tag object is found.

Parameters:
  `obj` - the starting object.
Returns:
  If `obj` is not an annotated tag, `obj`. Otherwise the first non-tag object that `obj` references. The returned object's headers have been parsed.
Throws:
  `MissingObjectException` - a referenced object cannot be found.
  `IOException` - a pack file or loose object could not be read.

#### newFlag

    public RevFlag newFlag(String name)

Create a new flag for application use during walking.

Applications are only assured to be able to create 24 unique flags on any given revision walker instance. Any flags beyond 24 are offered only if the implementation has extra free space within its internal storage.

Parameters:
  `name` - description of the flag, primarily useful for debugging.
Returns:
  newly constructed flag instance.
Throws:
  `IllegalArgumentException` - too many flags have been reserved on this revision walker.

#### carry

    public void carry(RevFlag flag)

Automatically carry a flag from a child commit to its parents.

A carried flag is copied from the child commit onto its parents when the child commit is popped from the lowest level of walk's internal graph.

Parameters:
  `flag` - the flag to carry onto parents, if set on a descendant.

#### carry

    public void carry(Collection<RevFlag> set)

Automatically carry flags from a child commit to its parents.

A carried flag is copied from the child commit onto its parents when the child commit is popped from the lowest level of walk's internal graph.

Parameters:
  `set` - the flags to carry onto parents, if set on a descendant.

#### retainOnReset

    public final void retainOnReset(RevFlag flag)

Preserve a RevFlag during all `reset` methods.

Calling `retainOnReset(flag)` avoids needing to pass the flag during each `resetRetain()` invocation on this instance.

Clearing flags marked retainOnReset requires disposing of the flag with `#disposeFlag(RevFlag)` or disposing of the entire RevWalk by `#dispose()`.

Parameters:
  `flag` - the flag to retain during all resets.
Since:
  3.6

#### retainOnReset

    public final void retainOnReset(Collection<RevFlag> flags)

Preserve a set of RevFlags during all `reset` methods.

Calling `retainOnReset(set)` avoids needing to pass the flags during each `resetRetain()` invocation on this instance.

Clearing flags marked retainOnReset requires disposing of the flag with `#disposeFlag(RevFlag)` or disposing of the entire RevWalk by `#dispose()`.

Parameters:
  `flags` - the flags to retain during all resets.
Since:
  3.6

#### disposeFlag

    public void disposeFlag(RevFlag flag)

Allow a flag to be recycled for a different use.

Recycled flags always come back as a different Java object instance when assigned again by `newFlag(String)`.

If the flag was previously being carried, the carrying request is removed. Disposing of a carried flag while a traversal is in progress has an undefined behavior.

Parameters:
  `flag` - the to recycle.

#### reset

    public final void reset()

Resets internal state and allows this instance to be used again.

Unlike `dispose()` previously acquired RevObject (and RevCommit) instances are not invalidated. RevFlag instances are not invalidated, but are removed from all RevObjects.

#### resetRetain

    public final void resetRetain(RevFlagSet retainFlags)

Resets internal state and allows this instance to be used again.

Unlike `dispose()` previously acquired RevObject (and RevCommit) instances are not invalidated. RevFlag instances are not invalidated, but are removed from all RevObjects.

Parameters:
  `retainFlags` - application flags that should not be cleared from existing commit objects.

#### resetRetain

    public final void resetRetain(RevFlag... retainFlags)

Resets internal state and allows this instance to be used again.

Unlike `dispose()` previously acquired RevObject (and RevCommit) instances are not invalidated. RevFlag instances are not invalidated, but are removed from all RevObjects.

See `retainOnReset(RevFlag)` for an alternative that does not require passing the flags during each reset.

Parameters:
  `retainFlags` - application flags that should not be cleared from existing commit objects.

#### reset

    protected void reset(int retainFlags)

Resets internal state and allows this instance to be used again.

Unlike `dispose()` previously acquired RevObject (and RevCommit) instances are not invalidated. RevFlag instances are not invalidated, but are removed from all RevObjects.

Parameters:
  `retainFlags` - application flags that should not be cleared from existing commit objects.

#### dispose

    public void dispose()

Dispose all internal state and invalidate all RevObject instances.

All RevObject (and thus RevCommit, etc.) instances previously acquired from this RevWalk are invalidated by a dispose call. Applications must not retain or use RevObject instances obtained prior to the dispose call. All RevFlag instances are also invalidated, and must not be reused.

#### iterator

    public Iterator<RevCommit> iterator()

Returns an Iterator over the commits of this walker.

The returned iterator is only useful for one walk. If this RevWalk gets reset a new iterator must be obtained to walk over the new results.

Applications must not use both the Iterator and the `next()` API at the same time. Pick one API and use that for the entire walk.

If a checked exception is thrown during the walk (see `next()`) it is rethrown from the Iterator as a `RevWalkException`.

Specified by:
  `iterator` in interface `Iterable<RevCommit>`
Returns:
  an iterator over this walker's commits.
See Also:
  `RevWalkException`

#### assertNotStarted

    protected void assertNotStarted()

Throws an exception if we have started producing output.

#### toObjectWalkWithSameObjects

    public ObjectWalk toObjectWalkWithSameObjects()

Create and return an `ObjectWalk` using the same objects.

Prior to using this method, the caller must reset this RevWalk to clean any flags that were used during the last traversal.

The returned ObjectWalk uses the same ObjectReader, internal object pool, and free RevFlags. Once the ObjectWalk is created, this RevWalk should not be used anymore.

Returns:
  a new walk, using the exact same object pool.

#### createCommit

    protected RevCommit createCommit(AnyObjectId id)

Construct a new unparsed commit for the given object.

Parameters:
  `id` - the object this walker requires a commit reference for.
Returns:
  a new unparsed reference for the object.

#### assumeShallow

    public void assumeShallow(Collection<? extends ObjectId> ids)

Assume additional commits are shallow (have no parents).

Parameters:
  `ids` - commits that should be treated as shallow commits, in addition to any commits already known to be shallow by the repository.
Since:
  3.3