Package org.eclipse.jgit.treewalk

## Class TreeWalk

- java.lang.Object
- - org.eclipse.jgit.treewalk.TreeWalk

Direct Known Subclasses:
  `NameConflictTreeWalk`

    public class TreeWalk
    extends Object

Walks one or more `AbstractTreeIterator`s in parallel.

This class can perform n-way differences across as many trees as necessary.

Each tree added must have the same root as existing trees in the walk.

A TreeWalk instance can only be used once to generate results. Running a second time requires creating a new TreeWalk instance, or invoking `reset()` and adding new trees before starting again. Resetting an existing instance may be faster for some applications as some internal buffers may be recycled.

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

Multiple simultaneous TreeWalk instances per `Repository` are permitted, even from concurrent threads.

### Constructor Summary

Constructors
`TreeWalk​(ObjectReader or)` Create a new tree walker for a given repository.
`TreeWalk​(Repository repo)` Create a new tree walker for a given repository.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`int` `addTree​(AnyObjectId id)` Add an already existing tree object for walking.
`int` `addTree​(AbstractTreeIterator p)` Add an already created tree iterator for walking.
`void` `enterSubtree()` Enter into the current subtree.
`static TreeWalk` `forPath​(ObjectReader reader, String path, AnyObjectId... trees)` Open a tree walk and filter to exactly one path.
`static TreeWalk` `forPath​(Repository db, String path, AnyObjectId... trees)` Open a tree walk and filter to exactly one path.
`static TreeWalk` `forPath​(Repository db, String path, RevTree tree)` Open a tree walk and filter to exactly one path.
`int` `getDepth()` Get the current subtree depth of this walker.
`FileMode` `getFileMode​(int nth)` Obtain the `FileMode` for the current entry.
`TreeFilter` `getFilter()` Get the currently configured filter.
`String` `getNameString()` Get the current entry's name within its parent tree.
`ObjectId` `getObjectId​(int nth)` Obtain the ObjectId for the current entry.
`void` `getObjectId​(MutableObjectId out, int nth)` Obtain the ObjectId for the current entry.
`ObjectReader` `getObjectReader()`
`int` `getPathLength()`
`String` `getPathString()` Get the current entry's complete path.
`int` `getRawMode​(int nth)` Obtain the raw `FileMode` bits for the current entry.
`byte[]` `getRawPath()` Get the current entry's complete path as a UTF-8 byte array.
`<T extends AbstractTreeIterator> T` `getTree​(int nth, Class<T> clazz)` Obtain the tree iterator for the current entry.
`int` `getTreeCount()` Get the number of trees known to this walker.
`boolean` `idEqual​(int nthA, int nthB)` Compare two tree's current ObjectId values for equality.
`int` `isPathPrefix​(byte[] p, int pLen)` Test if the supplied path matches the current entry's path.
`boolean` `isPathSuffix​(byte[] p, int pLen)` Test if the supplied path matches (being suffix of) the current entry's path.
`boolean` `isPostChildren()` Is the current entry a subtree returned after its children?
`boolean` `isPostOrderTraversal()` Does this walker return a tree entry after it exits the subtree?
`boolean` `isRecursive()` Is this walker automatically entering into subtrees?
`boolean` `isSubtree()` Is the current entry a subtree?
`boolean` `next()` Advance this walker to the next relevant entry.
`void` `release()` Release any resources used by this walker's reader.
`void` `reset()` Reset this walker so new tree iterators can be added to it.
`void` `reset​(AnyObjectId id)` Reset this walker to run over a single existing tree.
`void` `reset​(AnyObjectId... ids)` Reset this walker to run over a set of existing trees.
`void` `setFilter​(TreeFilter newFilter)` Set the tree entry filter for this walker.
`void` `setPostOrderTraversal​(boolean b)` Set the walker to return trees after their children.
`void` `setRecursive​(boolean b)` Set the walker to enter (or not enter) subtrees automatically.

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

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

### Constructor Detail

#### TreeWalk

    public TreeWalk​(Repository repo)

Create a new tree walker for a given repository.

Parameters:
  `repo` - the repository the walker will obtain data from.

#### TreeWalk

    public TreeWalk​(ObjectReader or)

Create a new tree walker for a given repository.

Parameters:
  `or` - the reader the walker will obtain tree data from.

### Method Detail

#### forPath

    public static TreeWalk forPath​(ObjectReader reader,
                                   String path,
                                   AnyObjectId... trees)
                            throws MissingObjectException,
                                   IncorrectObjectTypeException,
                                   CorruptObjectException,
                                   IOException

Open a tree walk and filter to exactly one path.

The returned tree walk is already positioned on the requested path, so the caller should not need to invoke `next()` unless they are looking for a possible directory/file name conflict.

Parameters:
  `reader` - the reader the walker will obtain tree data from.
  `path` - single path to advance the tree walk instance into.
  `trees` - one or more trees to walk through, all with the same root.
Returns:
  a new tree walk configured for exactly this one path; null if no path was found in any of the trees.
Throws:
  `IOException` - reading a pack file or loose object failed.
  `CorruptObjectException` - an tree object could not be read as its data stream did not appear to be a tree, or could not be inflated.
  `IncorrectObjectTypeException` - an object we expected to be a tree was not a tree.
  `MissingObjectException` - a tree object was not found.

#### forPath

    public static TreeWalk forPath​(Repository db,
                                   String path,
                                   AnyObjectId... trees)
                            throws MissingObjectException,
                                   IncorrectObjectTypeException,
                                   CorruptObjectException,
                                   IOException

Open a tree walk and filter to exactly one path.

The returned tree walk is already positioned on the requested path, so the caller should not need to invoke `next()` unless they are looking for a possible directory/file name conflict.

Parameters:
  `db` - repository to read tree object data from.
  `path` - single path to advance the tree walk instance into.
  `trees` - one or more trees to walk through, all with the same root.
Returns:
  a new tree walk configured for exactly this one path; null if no path was found in any of the trees.
Throws:
  `IOException` - reading a pack file or loose object failed.
  `CorruptObjectException` - an tree object could not be read as its data stream did not appear to be a tree, or could not be inflated.
  `IncorrectObjectTypeException` - an object we expected to be a tree was not a tree.
  `MissingObjectException` - a tree object was not found.

#### forPath

    public static TreeWalk forPath​(Repository db,
                                   String path,
                                   RevTree tree)
                            throws MissingObjectException,
                                   IncorrectObjectTypeException,
                                   CorruptObjectException,
                                   IOException

Open a tree walk and filter to exactly one path.

The returned tree walk is already positioned on the requested path, so the caller should not need to invoke `next()` unless they are looking for a possible directory/file name conflict.

Parameters:
  `db` - repository to read tree object data from.
  `path` - single path to advance the tree walk instance into.
  `tree` - the single tree to walk through.
Returns:
  a new tree walk configured for exactly this one path; null if no path was found in any of the trees.
Throws:
  `IOException` - reading a pack file or loose object failed.
  `CorruptObjectException` - an tree object could not be read as its data stream did not appear to be a tree, or could not be inflated.
  `IncorrectObjectTypeException` - an object we expected to be a tree was not a tree.
  `MissingObjectException` - a tree object was not found.

#### 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.

#### getFilter

    public TreeFilter getFilter()

Get the currently configured filter.

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

#### setFilter

    public void setFilter​(TreeFilter newFilter)

Set the tree entry filter for this walker.

Multiple filters may be combined by constructing an arbitrary tree of `AndTreeFilter` or `OrTreeFilter` 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 TreeWalk instances. Every TreeWalk must be supplied its own unique filter, unless the filter implementation specifically states it is (and always will be) thread-safe. Callers may use `TreeFilter.clone()` to create a unique filter tree for this TreeWalk instance.

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

#### isRecursive

    public boolean isRecursive()

Is this walker automatically entering into subtrees?

If the walker is recursive then the caller will not see a subtree node and instead will only receive file nodes in all relevant subtrees.

Returns:
  true if automatically entering subtrees is enabled.

#### setRecursive

    public void setRecursive​(boolean b)

Set the walker to enter (or not enter) subtrees automatically.

If recursive mode is enabled the walker will hide subtree nodes from the calling application and will produce only file level nodes. If a tree (directory) is deleted then all of the file level nodes will appear to be deleted, recursively, through as many levels as necessary to account for all entries.

Parameters:
  `b` - true to skip subtree nodes and only obtain files nodes.

#### isPostOrderTraversal

    public boolean isPostOrderTraversal()

Does this walker return a tree entry after it exits the subtree?

If post order traversal is enabled then the walker will return a subtree after it has returned the last entry within that subtree. This may cause a subtree to be seen by the application twice if `isRecursive()` is false, as the application will see it once, call `enterSubtree()`, and then see it again as it leaves the subtree.

If an application does not enable `isRecursive()` and it does not call `enterSubtree()` then the tree is returned only once as none of the children were processed.

Returns:
  true if subtrees are returned after entries within the subtree.

#### setPostOrderTraversal

    public void setPostOrderTraversal​(boolean b)

Set the walker to return trees after their children.

Parameters:
  `b` - true to get trees after their children.
See Also:
  `isPostOrderTraversal()`

#### reset

    public void reset()

Reset this walker so new tree iterators can be added to it.

#### reset

    public void reset​(AnyObjectId id)
               throws MissingObjectException,
                      IncorrectObjectTypeException,
                      CorruptObjectException,
                      IOException

Reset this walker to run over a single existing tree.

Parameters:
  `id` - the tree we need to parse. The walker will execute over this single tree if the reset is successful.
Throws:
  `MissingObjectException` - the given tree object does not exist in this repository.
  `IncorrectObjectTypeException` - the given object id does not denote a tree, but instead names some other non-tree type of object. Note that commits are not trees, even if they are sometimes called a "tree-ish".
  `CorruptObjectException` - the object claimed to be a tree, but its contents did not appear to be a tree. The repository may have data corruption.
  `IOException` - a loose object or pack file could not be read.

#### reset

    public void reset​(AnyObjectId... ids)
               throws MissingObjectException,
                      IncorrectObjectTypeException,
                      CorruptObjectException,
                      IOException

Reset this walker to run over a set of existing trees.

Parameters:
  `ids` - the trees we need to parse. The walker will execute over this many parallel trees if the reset is successful.
Throws:
  `MissingObjectException` - the given tree object does not exist in this repository.
  `IncorrectObjectTypeException` - the given object id does not denote a tree, but instead names some other non-tree type of object. Note that commits are not trees, even if they are sometimes called a "tree-ish".
  `CorruptObjectException` - the object claimed to be a tree, but its contents did not appear to be a tree. The repository may have data corruption.
  `IOException` - a loose object or pack file could not be read.

#### addTree

    public int addTree​(AnyObjectId id)
                throws MissingObjectException,
                       IncorrectObjectTypeException,
                       CorruptObjectException,
                       IOException

Add an already existing tree object for walking.

The position of this tree is returned to the caller, in case the caller has lost track of the order they added the trees into the walker.

The tree must have the same root as existing trees in the walk.

Parameters:
  `id` - identity of the tree object the caller wants walked.
Returns:
  position of this tree within the walker.
Throws:
  `MissingObjectException` - the given tree object does not exist in this repository.
  `IncorrectObjectTypeException` - the given object id does not denote a tree, but instead names some other non-tree type of object. Note that commits are not trees, even if they are sometimes called a "tree-ish".
  `CorruptObjectException` - the object claimed to be a tree, but its contents did not appear to be a tree. The repository may have data corruption.
  `IOException` - a loose object or pack file could not be read.

#### addTree

    public int addTree​(AbstractTreeIterator p)
                throws CorruptObjectException

Add an already created tree iterator for walking.

The position of this tree is returned to the caller, in case the caller has lost track of the order they added the trees into the walker.

The tree which the iterator operates on must have the same root as existing trees in the walk.

Parameters:
  `p` - an iterator to walk over. The iterator should be new, with no parent, and should still be positioned before the first entry. The tree which the iterator operates on must have the same root as other trees in the walk.
Returns:
  position of this tree within the walker.
Throws:
  `CorruptObjectException` - the iterator was unable to obtain its first entry, due to possible data corruption within the backing data store.

#### getTreeCount

    public int getTreeCount()

Get the number of trees known to this walker.

Returns:
  the total number of trees this walker is iterating over.

#### next

    public boolean next()
                 throws MissingObjectException,
                        IncorrectObjectTypeException,
                        CorruptObjectException,
                        IOException

Advance this walker to the next relevant entry.

Returns:
  true if there is an entry available; false if all entries have been walked and the walk of this set of tree iterators is over.
Throws:
  `MissingObjectException` - `isRecursive()` was enabled, a subtree was found, but the subtree object does not exist in this repository. The repository may be missing objects.
  `IncorrectObjectTypeException` - `isRecursive()` was enabled, a subtree was found, and the subtree id does not denote a tree, but instead names some other non-tree type of object. The repository may have data corruption.
  `CorruptObjectException` - the contents of a tree did not appear to be a tree. The repository may have data corruption.
  `IOException` - a loose object or pack file could not be read.

#### getTree

    public <T extends AbstractTreeIterator> T getTree​(int nth,
                                                      Class<T> clazz)

Obtain the tree iterator for the current entry.

Entering into (or exiting out of) a subtree causes the current tree iterator instance to be changed for the nth tree. This allows the tree iterators to manage only one list of items, with the diving handled by recursive trees.

Type Parameters:
  `T` - type of the tree iterator expected by the caller.
Parameters:
  `nth` - tree to obtain the current iterator of.
  `clazz` - type of the tree iterator expected by the caller.
Returns:
  r the current iterator of the requested type; null if the tree has no entry to match the current path.

#### getRawMode

    public int getRawMode​(int nth)

Obtain the raw `FileMode` bits for the current entry.

Every added tree supplies mode bits, even if the tree does not contain the current entry. In the latter case `FileMode.MISSING`'s mode bits (0) are returned.

Parameters:
  `nth` - tree to obtain the mode bits from.
Returns:
  mode bits for the current entry of the nth tree.
See Also:
  `FileMode.fromBits(int)`

#### getFileMode

    public FileMode getFileMode​(int nth)

Obtain the `FileMode` for the current entry.

Every added tree supplies a mode, even if the tree does not contain the current entry. In the latter case `FileMode.MISSING` is returned.

Parameters:
  `nth` - tree to obtain the mode from.
Returns:
  mode for the current entry of the nth tree.

#### getObjectId

    public ObjectId getObjectId​(int nth)

Obtain the ObjectId for the current entry.

Using this method to compare ObjectId values between trees of this walker is very inefficient. Applications should try to use `idEqual(int, int)` or `getObjectId(MutableObjectId, int)` whenever possible.

Every tree supplies an object id, even if the tree does not contain the current entry. In the latter case `ObjectId.zeroId()` is returned.

Parameters:
  `nth` - tree to obtain the object identifier from.
Returns:
  object identifier for the current tree entry.
See Also:
  `getObjectId(MutableObjectId, int)`, `idEqual(int, int)`

#### getObjectId

    public void getObjectId​(MutableObjectId out,
                            int nth)

Obtain the ObjectId for the current entry.

Every tree supplies an object id, even if the tree does not contain the current entry. In the latter case `ObjectId.zeroId()` is supplied.

Applications should try to use `idEqual(int, int)` when possible as it avoids conversion overheads.

Parameters:
  `out` - buffer to copy the object id into.
  `nth` - tree to obtain the object identifier from.
See Also:
  `idEqual(int, int)`

#### idEqual

    public boolean idEqual​(int nthA,
                           int nthB)

Compare two tree's current ObjectId values for equality.

Parameters:
  `nthA` - first tree to compare the object id from.
  `nthB` - second tree to compare the object id from.
Returns:
  result of `getObjectId(nthA).equals(getObjectId(nthB))`.
See Also:
  `getObjectId(int)`

#### getNameString

    public String getNameString()

Get the current entry's name within its parent tree.

This method is not very efficient and is primarily meant for debugging and final output generation. Applications should try to avoid calling it, and if invoked do so only once per interesting entry, where the name is absolutely required for correct function.

Returns:
  name of the current entry within the parent tree (or directory). The name never includes a '/'.

#### getPathString

    public String getPathString()

Get the current entry's complete path.

This method is not very efficient and is primarily meant for debugging and final output generation. Applications should try to avoid calling it, and if invoked do so only once per interesting entry, where the name is absolutely required for correct function.

Returns:
  complete path of the current entry, from the root of the repository. If the current entry is in a subtree there will be at least one '/' in the returned string.

#### getRawPath

    public byte[] getRawPath()

Get the current entry's complete path as a UTF-8 byte array.

Returns:
  complete path of the current entry, from the root of the repository. If the current entry is in a subtree there will be at least one '/' in the returned string.

#### getPathLength

    public int getPathLength()

Returns:
  The path length of the current entry.

#### isPathPrefix

    public int isPathPrefix​(byte[] p,
                            int pLen)

Test if the supplied path matches the current entry's path.

This method tests that the supplied path is exactly equal to the current entry, or is one of its parent directories. It is faster to use this method then to use `getPathString()` to first create a String object, then test `startsWith` or some other type of string match function.

Parameters:
  `p` - path buffer to test. Callers should ensure the path does not end with '/' prior to invocation.
  `pLen` - number of bytes from `buf` to test.
Returns:
  < 0 if p is before the current path; 0 if p matches the current path; 1 if the current path is past p and p will never match again on this tree walk.

#### isPathSuffix

    public boolean isPathSuffix​(byte[] p,
                                int pLen)

Test if the supplied path matches (being suffix of) the current entry's path.

This method tests that the supplied path is exactly equal to the current entry, or is relative to one of entry's parent directories. It is faster to use this method then to use `getPathString()` to first create a String object, then test `endsWith` or some other type of string match function.

Parameters:
  `p` - path buffer to test.
  `pLen` - number of bytes from `buf` to test.
Returns:
  true if p is suffix of the current path; false if otherwise

#### getDepth

    public int getDepth()

Get the current subtree depth of this walker.

Returns:
  the current subtree depth of this walker.

#### isSubtree

    public boolean isSubtree()

Is the current entry a subtree?

This method is faster then testing the raw mode bits of all trees to see if any of them are a subtree. If at least one is a subtree then this method will return true.

Returns:
  true if `enterSubtree()` will work on the current node.

#### isPostChildren

    public boolean isPostChildren()

Is the current entry a subtree returned after its children?

Returns:
  true if the current node is a tree that has been returned after its children were already processed.
See Also:
  `isPostOrderTraversal()`

#### enterSubtree

    public void enterSubtree()
                      throws MissingObjectException,
                             IncorrectObjectTypeException,
                             CorruptObjectException,
                             IOException

Enter into the current subtree.

If the current entry is a subtree this method arranges for its children to be returned before the next sibling following the subtree is returned.

Throws:
  `MissingObjectException` - a subtree was found, but the subtree object does not exist in this repository. The repository may be missing objects.
  `IncorrectObjectTypeException` - a subtree was found, and the subtree id does not denote a tree, but instead names some other non-tree type of object. The repository may have data corruption.
  `CorruptObjectException` - the contents of a tree did not appear to be a tree. The repository may have data corruption.
  `IOException` - a loose object or pack file could not be read.