Top Description Inners Fields Constructors Methods
org.eclipse.jgit.treewalk.filter

public abstract Class TreeFilter

extends Object
Class Inheritance
Known Direct Subclasses
org.eclipse.jgit.treewalk.filter.TreeFilter.AllFilter, org.eclipse.jgit.treewalk.filter.TreeFilter.AnyDiffFilter, org.eclipse.jgit.lib.IndexDiff.ProgressReportingFilter, org.eclipse.jgit.revwalk.FollowFilter, org.eclipse.jgit.treewalk.filter.AndTreeFilter, org.eclipse.jgit.treewalk.filter.IndexDiffFilter, org.eclipse.jgit.treewalk.filter.InterIndexDiffFilter, org.eclipse.jgit.treewalk.filter.NotIgnoredFilter, org.eclipse.jgit.treewalk.filter.NotTreeFilter, org.eclipse.jgit.treewalk.filter.OrTreeFilter, org.eclipse.jgit.treewalk.filter.PathFilter, org.eclipse.jgit.treewalk.filter.PathFilterGroup.Single, org.eclipse.jgit.treewalk.filter.PathFilterGroup.Group, org.eclipse.jgit.treewalk.filter.PathSuffixFilter, org.eclipse.jgit.treewalk.filter.SkipWorkTreeFilter
Imports
java.io.IOException, java.util.Optional, .Set, org.eclipse.jgit.dircache.DirCacheIterator, org.eclipse.jgit.errors.IncorrectObjectTypeException, .MissingObjectException, org.eclipse.jgit.treewalk.TreeWalk, .WorkingTreeIterator

Selects interesting tree entries during walking.

This is an abstract interface. Applications may implement a subclass, or use one of the predefined implementations already available within this package.

Unless specifically noted otherwise a TreeFilter implementation is not thread safe and may not be shared by different TreeWalk instances at the same time. This restriction allows TreeFilter implementations to cache state within their instances during include(TreeWalk) if it is beneficial to their implementation. Deep clones created by clone() may be used to construct a thread-safe copy of an existing filter.

Path filters:

Difference filters:

Boolean modifiers:

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
private static class

Field Summary

Modifier and TypeField and Description
public static final TreeFilter
ALL

Selects all tree entries.

public static final TreeFilter
ANY_DIFF

Selects only tree entries which differ between at least 2 trees.

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public abstract TreeFilter
clone()

Overrides java.lang.Object.clone.

Creates and returns a copy of this object.

public Optional<Set<byte[]>>

Returns:

a set of paths, or empty
getPathsBestEffort
()

If this filter checks that at least one of the paths in a set has been modified, returns that set of paths to be checked against a changed path filter.

public abstract boolean

Returns:

true if the current entry should be seen by the application; false to hide the entry.
include
(TreeWalk
the walker the filter needs to examine.
walker
)

Determine if the current entry is interesting to report.

public int

Returns:

-1 if the current entry is a parent of the filter but no exact match has been made; 0 if the current entry should be seen by the application; 1 if it should be hidden.
matchFilter
(TreeWalk
the walker the filter needs to examine.
walker
)

Determine if the current entry is a parent, a match, or no match.

public TreeFilter

Returns:

a new filter that includes tree entries this filter rejects.
negate
()

Create a new filter that does the opposite of this filter.

public abstract boolean

Returns:

true if the filter would like to have the walker recurse into subtrees to make sure it matches everything correctly; false if the filter does not require entering subtrees.
shouldBeRecursive
()

Does this tree filter require a recursive walk to match everything?

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Inherited from java.lang.Object:
equalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

ALLback to summary
public static final TreeFilter ALL

Selects all tree entries.

ANY_DIFFback to summary
public static final TreeFilter ANY_DIFF

Selects only tree entries which differ between at least 2 trees.

This filter also prevents a TreeWalk from recursing into a subtree if all parent trees have the identical subtree at the same path. This dramatically improves walk performance as only the changed subtrees are entered into.

If this filter is applied to a walker with only one tree it behaves like ALL, or as though the walker was matching a virtual empty tree against the single tree it was actually given. Applications may wish to treat such a difference as "all names added".

When comparing WorkingTreeIterator and DirCacheIterator applications should use IndexDiffFilter.

Constructor Detail

TreeFilterback to summary
public TreeFilter()

Method Detail

cloneback to summary
public abstract TreeFilter clone()

Overrides java.lang.Object.clone.

Doc from java.lang.Object.clone.

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:

x.clone() != x
will be true, and that the expression:
x.clone().getClass() == x.getClass()
will be true, but these are not absolute requirements. While it is typically the case that:
x.clone().equals(x)
will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified. Clone this tree filter, including its parameters.

This is a deep clone. If this filter embeds objects or other filters it must also clone those, to ensure the instances do not share mutable data.

Returns:TreeFilter

a clone of this instance.

Annotations
@Override
getPathsBestEffortback to summary
public Optional<Set<byte[]>> getPathsBestEffort()

If this filter checks that at least one of the paths in a set has been modified, returns that set of paths to be checked against a changed path filter. Otherwise, returns empty.

Returns:Optional<Set<byte[]>>

a set of paths, or empty

Since
6.7
includeback to summary
public abstract boolean include(TreeWalk walker) throws MissingObjectException, IncorrectObjectTypeException, IOException

Determine if the current entry is interesting to report.

This method is consulted for subtree entries even if org.eclipse.jgit.treewalk.TreeWalk#isRecursive() is enabled. The consultation allows the filter to bypass subtree recursion on a case-by-case basis, even when recursion is enabled at the application level.

Parameters
walker:TreeWalk

the walker the filter needs to examine.

Returns:boolean

true if the current entry should be seen by the application; false to hide the entry.

Exceptions
MissingObjectException:
an object the filter needs to consult to determine its answer does not exist in the Git repository the walker is operating on. Filtering this current walker entry is impossible without the object.
IncorrectObjectTypeException:
an object the filter needed to consult was not of the expected object type. This usually indicates a corrupt repository, as an object link is referencing the wrong type.
IOException:
a loose object or pack file could not be read to obtain data necessary for the filter to make its decision.
matchFilterback to summary
public int matchFilter(TreeWalk walker) throws MissingObjectException, IncorrectObjectTypeException, IOException

Determine if the current entry is a parent, a match, or no match.

This method extends the result returned by include(TreeWalk) with a third option (-1), splitting the value true. This gives the application a possibility to distinguish between an exact match and the case when a subtree to the current entry might be a match.

Parameters
walker:TreeWalk

the walker the filter needs to examine.

Returns:int

-1 if the current entry is a parent of the filter but no exact match has been made; 0 if the current entry should be seen by the application; 1 if it should be hidden.

Exceptions
MissingObjectException:
as thrown by include(TreeWalk)
IncorrectObjectTypeException:
as thrown by include(TreeWalk)
IOException:
as thrown by include(TreeWalk)
Since
4.7
negateback to summary
public TreeFilter negate()

Create a new filter that does the opposite of this filter.

Returns:TreeFilter

a new filter that includes tree entries this filter rejects.

shouldBeRecursiveback to summary
public abstract boolean shouldBeRecursive()

Does this tree filter require a recursive walk to match everything?

If this tree filter is matching on full entry path names and its pattern is looking for a '/' then the filter would require a recursive TreeWalk to accurately make its decisions. The walker is not required to enable recursive behavior for any particular filter, this is only a hint.

Returns:boolean

true if the filter would like to have the walker recurse into subtrees to make sure it matches everything correctly; false if the filter does not require entering subtrees.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations
@Override
org.eclipse.jgit.treewalk.filter back to summary

private final Class TreeFilter.AllFilter

extends TreeFilter
Class Inheritance

Field Summary

Inherited from org.eclipse.jgit.treewalk.filter.TreeFilter:
ALLANY_DIFF

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public TreeFilter
clone()

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.clone.

Creates and returns a copy of this object.

public boolean
include(TreeWalk
the walker the filter needs to examine.
walker
)

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.include.

Determine if the current entry is interesting to report.

public boolean
shouldBeRecursive()

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.shouldBeRecursive.

Does this tree filter require a recursive walk to match everything?

public String
toString()

Overrides org.eclipse.jgit.treewalk.filter.TreeFilter.toString.

Returns a string representation of the object.

Inherited from org.eclipse.jgit.treewalk.filter.TreeFilter:
getPathsBestEffortmatchFilternegate

Constructor Detail

AllFilterback to summary
private AllFilter()

Method Detail

cloneback to summary
public TreeFilter clone()

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.clone.

Doc from org.eclipse.jgit.treewalk.filter.TreeFilter.clone.

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:

x.clone() != x
will be true, and that the expression:
x.clone().getClass() == x.getClass()
will be true, but these are not absolute requirements. While it is typically the case that:
x.clone().equals(x)
will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified. Clone this tree filter, including its parameters.

This is a deep clone. If this filter embeds objects or other filters it must also clone those, to ensure the instances do not share mutable data.

Returns:TreeFilter

Doc from java.lang.Object.clone.

a clone of this instance.

Annotations
@Override
includeback to summary
public boolean include(TreeWalk walker)

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.include.

Doc from org.eclipse.jgit.treewalk.filter.TreeFilter.include.

Determine if the current entry is interesting to report.

This method is consulted for subtree entries even if org.eclipse.jgit.treewalk.TreeWalk#isRecursive() is enabled. The consultation allows the filter to bypass subtree recursion on a case-by-case basis, even when recursion is enabled at the application level.

Parameters
walker:TreeWalk

the walker the filter needs to examine.

Returns:boolean

true if the current entry should be seen by the application; false to hide the entry.

Annotations
@Override
shouldBeRecursiveback to summary
public boolean shouldBeRecursive()

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.shouldBeRecursive.

Doc from org.eclipse.jgit.treewalk.filter.TreeFilter.shouldBeRecursive.

Does this tree filter require a recursive walk to match everything?

If this tree filter is matching on full entry path names and its pattern is looking for a '/' then the filter would require a recursive TreeWalk to accurately make its decisions. The walker is not required to enable recursive behavior for any particular filter, this is only a hint.

Returns:boolean

true if the filter would like to have the walker recurse into subtrees to make sure it matches everything correctly; false if the filter does not require entering subtrees.

Annotations
@Override
toStringback to summary
public String toString()

Overrides org.eclipse.jgit.treewalk.filter.TreeFilter.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations
@Override
org.eclipse.jgit.treewalk.filter back to summary

private final Class TreeFilter.AnyDiffFilter

extends TreeFilter
Class Inheritance

Field Summary

Modifier and TypeField and Description
private static final int
Inherited from org.eclipse.jgit.treewalk.filter.TreeFilter:
ALLANY_DIFF

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public TreeFilter
clone()

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.clone.

Creates and returns a copy of this object.

public boolean
include(TreeWalk
the walker the filter needs to examine.
walker
)

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.include.

Determine if the current entry is interesting to report.

public boolean
shouldBeRecursive()

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.shouldBeRecursive.

Does this tree filter require a recursive walk to match everything?

public String
toString()

Overrides org.eclipse.jgit.treewalk.filter.TreeFilter.toString.

Returns a string representation of the object.

Inherited from org.eclipse.jgit.treewalk.filter.TreeFilter:
getPathsBestEffortmatchFilternegate

Field Detail

baseTreeback to summary
private static final int baseTree

Constructor Detail

AnyDiffFilterback to summary
private AnyDiffFilter()

Method Detail

cloneback to summary
public TreeFilter clone()

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.clone.

Doc from org.eclipse.jgit.treewalk.filter.TreeFilter.clone.

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:

x.clone() != x
will be true, and that the expression:
x.clone().getClass() == x.getClass()
will be true, but these are not absolute requirements. While it is typically the case that:
x.clone().equals(x)
will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified. Clone this tree filter, including its parameters.

This is a deep clone. If this filter embeds objects or other filters it must also clone those, to ensure the instances do not share mutable data.

Returns:TreeFilter

Doc from java.lang.Object.clone.

a clone of this instance.

Annotations
@Override
includeback to summary
public boolean include(TreeWalk walker)

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.include.

Doc from org.eclipse.jgit.treewalk.filter.TreeFilter.include.

Determine if the current entry is interesting to report.

This method is consulted for subtree entries even if org.eclipse.jgit.treewalk.TreeWalk#isRecursive() is enabled. The consultation allows the filter to bypass subtree recursion on a case-by-case basis, even when recursion is enabled at the application level.

Parameters
walker:TreeWalk

the walker the filter needs to examine.

Returns:boolean

true if the current entry should be seen by the application; false to hide the entry.

Annotations
@Override
shouldBeRecursiveback to summary
public boolean shouldBeRecursive()

Implements abstract org.eclipse.jgit.treewalk.filter.TreeFilter.shouldBeRecursive.

Doc from org.eclipse.jgit.treewalk.filter.TreeFilter.shouldBeRecursive.

Does this tree filter require a recursive walk to match everything?

If this tree filter is matching on full entry path names and its pattern is looking for a '/' then the filter would require a recursive TreeWalk to accurately make its decisions. The walker is not required to enable recursive behavior for any particular filter, this is only a hint.

Returns:boolean

true if the filter would like to have the walker recurse into subtrees to make sure it matches everything correctly; false if the filter does not require entering subtrees.

Annotations
@Override
toStringback to summary
public String toString()

Overrides org.eclipse.jgit.treewalk.filter.TreeFilter.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations
@Override