Package org.eclipse.jgit.treewalk

## Class WorkingTreeIterator

- java.lang.Object
- - org.eclipse.jgit.treewalk.AbstractTreeIterator
  - - org.eclipse.jgit.treewalk.WorkingTreeIterator

Direct Known Subclasses:
  `FileTreeIterator`

    public abstract class WorkingTreeIterator
    extends AbstractTreeIterator

Walks a working directory tree as part of a `TreeWalk`.

Most applications will want to use the standard implementation of this iterator, `FileTreeIterator`, as that does all IO through the standard `java.io` package. Plugins for a Java based IDE may however wish to create their own implementations of this class to allow traversal of the IDE's project space, as well as benefit from any caching the IDE may have.

See Also:
  `FileTreeIterator`

### Nested Class Summary

Nested Classes
`protected static class` `WorkingTreeIterator.Entry` A single entry within a working directory tree.
`static class` `WorkingTreeIterator.MetadataDiff` The result of a metadata-comparison between the current entry and a `DirCacheEntry`

### Field Summary

Fields
`protected static WorkingTreeIterator.Entry[]` `EOF` An empty entry array, suitable for `init(Entry[])`.
`protected Repository` `repository` Repository that is the root level being iterated over

### Fields inherited from class org.eclipse.jgit.treewalk.AbstractTreeIterator

`DEFAULT_PATH_SIZE, mode, path, pathLen, pathOffset, zeroid`

### Constructor Summary

Constructors
`protected` `WorkingTreeIterator​(String prefix, WorkingTreeOptions options)` Create a new iterator with no parent and a prefix.
`protected` `WorkingTreeIterator​(WorkingTreeIterator p)` Create an iterator for a subtree of an existing iterator.
`protected` `WorkingTreeIterator​(WorkingTreeOptions options)` Create a new iterator with no parent.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`void` `back​(int delta)` Move to prior entry, populating this iterator with the entry data.
`WorkingTreeIterator.MetadataDiff` `compareMetadata​(DirCacheEntry entry)` Compare the metadata (mode, length, modification-timestamp) of the current entry and a `DirCacheEntry`
`protected WorkingTreeIterator.Entry` `current()` Obtain the current entry from this iterator.
`boolean` `eof()` Is this tree iterator at its EOF point (no more entries)?
`boolean` `first()` Is this tree iterator positioned on its first entry?
`AttributesNode` `getEntryAttributesNode()` Retrieves the `AttributesNode` for the current entry.
`long` `getEntryContentLength()` Get the filtered input length of this entry
`long` `getEntryLastModified()` Get the last modified time of this entry.
`long` `getEntryLength()` Get the raw byte length of this entry.
`AttributesNode` `getGlobalAttributesNode()` Retrieves the `AttributesNode` that holds the information located in system-wide file.
`FileMode` `getIndexFileMode​(DirCacheIterator indexIter)` Get the file mode to use for the current entry when it is to be updated in the index.
`AttributesNode` `getInfoAttributesNode()` Retrieves the `AttributesNode` that holds the information located in $GIT_DIR/info/attributes file.
`WorkingTreeOptions` `getOptions()` Returns the working tree options used by this iterator.
`boolean` `hasId()`
`byte[]` `idBuffer()` Get the byte array buffer object IDs must be copied out of.
`int` `idOffset()` Get the position within `AbstractTreeIterator.idBuffer()` of this entry's ObjectId.
`protected byte[]` `idSubmodule​(File directory, WorkingTreeIterator.Entry e)` Get submodule id using the repository at the location of the entry relative to the directory.
`protected byte[]` `idSubmodule​(WorkingTreeIterator.Entry e)` Get submodule id for given entry.
`protected void` `init​(WorkingTreeIterator.Entry[] list)` Constructor helper.
`protected void` `initRootIterator​(Repository repo)` Initialize this iterator for the root level of a repository.
`boolean` `isEntryIgnored()` Determine if the current entry path is ignored by an ignore rule.
`protected boolean` `isEntryIgnored​(int pLen)` Determine if the entry path is ignored by an ignore rule.
`boolean` `isModeDifferent​(int rawMode)` Is the file mode of the current entry different than the given raw mode?
`boolean` `isModified​(DirCacheEntry entry, boolean forceContentCheck)` Deprecated. Use `isModified(DirCacheEntry, boolean, ObjectReader)`
`boolean` `isModified​(DirCacheEntry entry, boolean forceContentCheck, ObjectReader reader)` Checks whether this entry differs from a given entry from the `DirCache`.
`void` `next​(int delta)` Move to next entry, populating this iterator with the entry data.
`InputStream` `openEntryStream()` Obtain an input stream to read the file content.
`void` `reset()` Position this iterator on the first entry.
`void` `setDirCacheIterator​(TreeWalk walk, int treeId)` Define the matching `DirCacheIterator`, to optimize ObjectIds.

### Methods inherited from class org.eclipse.jgit.treewalk.AbstractTreeIterator

`createEmptyTreeIterator, createSubtreeIterator, createSubtreeIterator, ensurePathCapacity, getEntryFileMode, getEntryObjectId, getEntryObjectId, getEntryPathBuffer, getEntryPathHashCode, getEntryPathLength, getEntryPathString, getEntryRawMode, getName, getNameLength, getNameOffset, growPath, idEqual, pathCompare, pathCompare, skip, stopWalk, toString`

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

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

### Field Detail

#### EOF

    protected static final WorkingTreeIterator.Entry[] EOF

An empty entry array, suitable for `init(Entry[])`.

#### repository

    protected Repository repository

Repository that is the root level being iterated over

### Constructor Detail

#### WorkingTreeIterator

    protected WorkingTreeIterator​(WorkingTreeOptions options)

Create a new iterator with no parent.

Parameters:
  `options` - working tree options to be used

#### WorkingTreeIterator

    protected WorkingTreeIterator​(String prefix,
                                  WorkingTreeOptions options)

Create a new iterator with no parent and a prefix.

The prefix path supplied is inserted in front of all paths generated by this iterator. It is intended to be used when an iterator is being created for a subsection of an overall repository and needs to be combined with other iterators that are created to run over the entire repository namespace.

Parameters:
  `prefix` - position of this iterator in the repository tree. The value may be null or the empty string to indicate the prefix is the root of the repository. A trailing slash ('/') is automatically appended if the prefix does not end in '/'.
  `options` - working tree options to be used

#### WorkingTreeIterator

    protected WorkingTreeIterator​(WorkingTreeIterator p)

Create an iterator for a subtree of an existing iterator.

Parameters:
  `p` - parent tree iterator.

### Method Detail

#### initRootIterator

    protected void initRootIterator​(Repository repo)

Initialize this iterator for the root level of a repository.

This method should only be invoked after calling `init(Entry[])`, and only for the root iterator.

Parameters:
  `repo` - the repository.

#### setDirCacheIterator

    public void setDirCacheIterator​(TreeWalk walk,
                                    int treeId)

Define the matching `DirCacheIterator`, to optimize ObjectIds. Once the DirCacheIterator has been set this iterator must only be advanced by the TreeWalk that is supplied, as it assumes that itself and the corresponding DirCacheIterator are positioned on the same file path whenever `idBuffer()` is invoked.

Parameters:
  `walk` - the walk that will be advancing this iterator.
  `treeId` - index of the matching `DirCacheIterator`.

#### hasId

    public boolean hasId()

Specified by:
  `hasId` in class `AbstractTreeIterator`
Returns:
  true if the entry has a valid ObjectId.

#### idBuffer

    public byte[] idBuffer()

Description copied from class: `AbstractTreeIterator`
Get the byte array buffer object IDs must be copied out of.

The id buffer contains the bytes necessary to construct an ObjectId for the current entry of this iterator. The buffer can be the same buffer for all entries, or it can be a unique buffer per-entry. Implementations are encouraged to expose their private buffer whenever possible to reduce garbage generation and copying costs.

Specified by:
  `idBuffer` in class `AbstractTreeIterator`
Returns:
  byte array the implementation stores object IDs within.
See Also:
  `AbstractTreeIterator.getEntryObjectId()`

#### idSubmodule

    protected byte[] idSubmodule​(WorkingTreeIterator.Entry e)

Get submodule id for given entry.

Parameters:
  `e` -
Returns:
  non-null submodule id

#### idSubmodule

    protected byte[] idSubmodule​(File directory,
                                 WorkingTreeIterator.Entry e)

Get submodule id using the repository at the location of the entry relative to the directory.

Parameters:
  `directory` -
  `e` -
Returns:
  non-null submodule id

#### getOptions

    public WorkingTreeOptions getOptions()

Returns the working tree options used by this iterator.

Returns:
  working tree options

#### idOffset

    public int idOffset()

Description copied from class: `AbstractTreeIterator`
Get the position within `AbstractTreeIterator.idBuffer()` of this entry's ObjectId.

Specified by:
  `idOffset` in class `AbstractTreeIterator`
Returns:
  offset into the array returned by `AbstractTreeIterator.idBuffer()` where the ObjectId must be copied out of.

#### reset

    public void reset()

Description copied from class: `AbstractTreeIterator`
Position this iterator on the first entry. The default implementation of this method uses `back(1)` until `first()` is true. This is most likely not the most efficient method of repositioning the iterator to its first entry, so subclasses are strongly encouraged to override the method.

Overrides:
  `reset` in class `AbstractTreeIterator`

#### first

    public boolean first()

Description copied from class: `AbstractTreeIterator`
Is this tree iterator positioned on its first entry?

An iterator is positioned on the first entry if `back(1)` would be an invalid request as there is no entry before the current one.

An empty iterator (one with no entries) will be `first() && eof()`.

Specified by:
  `first` in class `AbstractTreeIterator`
Returns:
  true if the iterator is positioned on the first entry.

#### eof

    public boolean eof()

Description copied from class: `AbstractTreeIterator`
Is this tree iterator at its EOF point (no more entries)?

An iterator is at EOF if there is no current entry.

Specified by:
  `eof` in class `AbstractTreeIterator`
Returns:
  true if we have walked all entries and have none left.

#### next

    public void next​(int delta)
              throws CorruptObjectException

Description copied from class: `AbstractTreeIterator`
Move to next entry, populating this iterator with the entry data.

The delta indicates how many moves forward should occur. The most common delta is 1 to move to the next entry.

Implementations must populate the following members:

- `AbstractTreeIterator.mode`
- `AbstractTreeIterator.path` (from `AbstractTreeIterator.pathOffset` to `AbstractTreeIterator.pathLen`)
- `AbstractTreeIterator.pathLen`

as well as any implementation dependent information necessary to accurately return data from `AbstractTreeIterator.idBuffer()` and `AbstractTreeIterator.idOffset()` when demanded.

Specified by:
  `next` in class `AbstractTreeIterator`
Parameters:
  `delta` - number of entries to move the iterator by. Must be a positive, non-zero integer.
Throws:
  `CorruptObjectException` - the tree is invalid.

#### back

    public void back​(int delta)
              throws CorruptObjectException

Description copied from class: `AbstractTreeIterator`
Move to prior entry, populating this iterator with the entry data.

The delta indicates how many moves backward should occur.The most common delta is 1 to move to the prior entry.

Implementations must populate the following members:

- `AbstractTreeIterator.mode`
- `AbstractTreeIterator.path` (from `AbstractTreeIterator.pathOffset` to `AbstractTreeIterator.pathLen`)
- `AbstractTreeIterator.pathLen`

as well as any implementation dependent information necessary to accurately return data from `AbstractTreeIterator.idBuffer()` and `AbstractTreeIterator.idOffset()` when demanded.

Specified by:
  `back` in class `AbstractTreeIterator`
Parameters:
  `delta` - number of entries to move the iterator by. Must be a positive, non-zero integer.
Throws:
  `CorruptObjectException` - the tree is invalid.

#### getEntryLength

    public long getEntryLength()

Get the raw byte length of this entry.

Returns:
  size of this file, in bytes.

#### getEntryContentLength

    public long getEntryContentLength()
                               throws IOException

Get the filtered input length of this entry

Returns:
  size of the content, in bytes
Throws:
  `IOException`

#### getEntryLastModified

    public long getEntryLastModified()

Get the last modified time of this entry.

Returns:
  last modified time of this file, in milliseconds since the epoch (Jan 1, 1970 UTC).

#### openEntryStream

    public InputStream openEntryStream()
                                throws IOException

Obtain an input stream to read the file content.

Efficient implementations are not required. The caller will usually obtain the stream only once per entry, if at all.

The input stream should not use buffering if the implementation can avoid it. The caller will buffer as necessary to perform efficient block IO operations.

The caller will close the stream once complete.

Returns:
  a stream to read from the file.
Throws:
  `IOException` - the file could not be opened for reading.

#### isEntryIgnored

    public boolean isEntryIgnored()
                           throws IOException

Determine if the current entry path is ignored by an ignore rule.

Returns:
  true if the entry was ignored by an ignore rule file.
Throws:
  `IOException` - a relevant ignore rule file exists but cannot be read.

#### isEntryIgnored

    protected boolean isEntryIgnored​(int pLen)
                              throws IOException

Determine if the entry path is ignored by an ignore rule.

Parameters:
  `pLen` - the length of the path in the path buffer.
Returns:
  true if the entry is ignored by an ignore rule.
Throws:
  `IOException` - a relevant ignore rule file exists but cannot be read.

#### getEntryAttributesNode

    public AttributesNode getEntryAttributesNode()
                                          throws IOException

Retrieves the `AttributesNode` for the current entry.

Returns:
  `AttributesNode` for the current entry.
Throws:
  `IOException` - if an error is raised while parsing the .gitattributes file
Since:
  3.7

#### getInfoAttributesNode

    public AttributesNode getInfoAttributesNode()
                                         throws IOException

Retrieves the `AttributesNode` that holds the information located in $GIT_DIR/info/attributes file.

Returns:
  the `AttributesNode` that holds the information located in $GIT_DIR/info/attributes file.
Throws:
  `IOException` - if an error is raised while parsing the attributes file
Since:
  3.7

#### getGlobalAttributesNode

    public AttributesNode getGlobalAttributesNode()
                                           throws IOException

Retrieves the `AttributesNode` that holds the information located in system-wide file.

Returns:
  the `AttributesNode` that holds the information located in system-wide file.
Throws:
  `IOException` - IOException if an error is raised while parsing the attributes file
Since:
  3.7
See Also:
  `CoreConfig.getAttributesFile()`

#### init

    protected void init​(WorkingTreeIterator.Entry[] list)

Constructor helper.

Parameters:
  `list` - files in the subtree of the work tree this iterator operates on

#### current

    protected WorkingTreeIterator.Entry current()

Obtain the current entry from this iterator.

Returns:
  the currently selected entry.

#### isModeDifferent

    public boolean isModeDifferent​(int rawMode)

Is the file mode of the current entry different than the given raw mode?

Parameters:
  `rawMode` -
Returns:
  true if different, false otherwise

#### compareMetadata

    public WorkingTreeIterator.MetadataDiff compareMetadata​(DirCacheEntry entry)

Compare the metadata (mode, length, modification-timestamp) of the current entry and a `DirCacheEntry`

Parameters:
  `entry` - the `DirCacheEntry` to compare with
Returns:
  a `WorkingTreeIterator.MetadataDiff` which tells whether and how the entries metadata differ

#### isModified

    @Deprecated
    public boolean isModified​(DirCacheEntry entry,
                              boolean forceContentCheck)

Deprecated.
Use `isModified(DirCacheEntry, boolean, ObjectReader)`
Checks whether this entry differs from a given entry from the `DirCache`. File status information is used and if status is same we consider the file identical to the state in the working directory. Native git uses more stat fields than we have accessible in Java.

Parameters:
  `entry` - the entry from the dircache we want to compare against
  `forceContentCheck` - True if the actual file content should be checked if modification time differs.
Returns:
  true if content is most likely different.

#### isModified

    public boolean isModified​(DirCacheEntry entry,
                              boolean forceContentCheck,
                              ObjectReader reader)
                       throws IOException

Checks whether this entry differs from a given entry from the `DirCache`. File status information is used and if status is same we consider the file identical to the state in the working directory. Native git uses more stat fields than we have accessible in Java.

Parameters:
  `entry` - the entry from the dircache we want to compare against
  `forceContentCheck` - True if the actual file content should be checked if modification time differs.
  `reader` - access to repository objects if necessary. Should not be null.
Returns:
  true if content is most likely different.
Throws:
  `IOException`
Since:
  3.3

#### getIndexFileMode

    public FileMode getIndexFileMode​(DirCacheIterator indexIter)

Get the file mode to use for the current entry when it is to be updated in the index.

Parameters:
  `indexIter` - `DirCacheIterator` positioned at the same entry as this iterator or null if no `DirCacheIterator` is available at this iterator's current entry
Returns:
  index file mode