View source for JGit/User Guide

= Incompatible JGit API Changes =
JGit is still in beta hence we sometimes do incompatible API changes to reach a better stable API.
<br>These are listed here as a reference for other projects depending on the JGit API.

== Version 0.9 ==

''RepositoryConfig removed'':  Use Config or FileBasedConfig instead.  To replace getCore(), getTransfer() and getUserConfig() methods, use config.get(CoreConfig.KEY), config.get(TransferConfig.KEY), and config.get(UserConfig.KEY).  To replace getAuthorName() and friends, use the UserConfig object returned by config.get(UserConfig.KEY).

''Repository class is abstract'':  Use a RepositoryBuilder.

''Repository constructors removed'':  To create a Repository instance, use a RepositoryBuilder.  If you know it must be a classical local file system based Repository (as opposed to other types that JGit will support in the future), you can use the FileRepositoryBuilder instead to ensure its a FileRepository that is returned.

''Repository.getDirectory() can return null'':  It is no longer a requirement that every Repository instance has a java.io.File associated with it.  In the future some types of Git repositories that are not on the local filesystem will be supported, and those types will return null.

''Repository.getWorkDir() renamed'':  The method is now called getWorkTree().

''Repository.openObject(), openBlob(), renamed'':  To read an object, use Repository.open() or repository.newObjectReader() to get a reader and use the reader's open() method.  An ObjectReader is preferred if the application will access several objects in a short time span (e.g. in response to the current UI event, or the current network connection).

''Repository.hasObject() renamed'':  To check if an object exists, use has(AnyObjectId) instead.

''Repository.open() checks existence, type'':  The open object methods on Repository, ObjectDatabase and ObjectReader now check that an object exists, and if not throws ObjectNotFoundException.  If the type hint is supplied, they also validate that the object is actually of the type hint, or throw IncorrectObjectTypeException.  This simplifies most application code, as null is no longer a valid return value.

''Repository event listener changes'':  Repository events are now delivered through a completely different API.  Each event type has a corresponding Listener interface to receive that event, and listeners must be registered through the Repository.getListenerList().add*Listener().

''RepositoryState value BARE added'':  To correctly denote a bare repository whose work tree state is undefined, the enum RepositoryState returned by repository.getRepositoryState() returns BARE when isBare() is true or getDirectory() returns null.

''WindowCursor removed'':  Instead use repository.newObjectReader(), and examine objects through the methods on the returned ObjectReader.  Please note that an ObjectReader must be released with its release() method after it is no longer useful to the application.

''RevWalk requires release'':  RevWalk now embeds an ObjectReader, and therefore must be released through its release() method when it is no longer required by the application that created it.  Optionally the caller can now specify the ObjectReader the walker should use, allowing the caller to more explicitly manage the release.

''TreeWalk requires release'':  TreeWalk now embeds an ObjectReader, and therefore must be released through its release() method when it is no longer required by the application that created it.  Optionally the caller can now specify the ObjectReader the walker should use, allowing the caller to more explicitly manage the release.

''ObjectWriter deprecated'':  ObjectWriter will be removed in a future version of JGit.  Applications are strongly encouraged to switch to the ObjectInserter API, which can be obtained from repository.newObjectInserter().  Like the ObjectReader, an ObjectInserter must be released through its release() method after use.

''NoWorkTreeException thrown'':  A bare repository (one without a working directory) will throw NoWorkTreeException if its getIndexFile(), getIndex(), getWorkTree(), readCommitMessage(), or readMergeMessage() is called on it, or if its corresponding DirCache is read or locked.  This is a RuntimeException so applications need to be careful about knowing what the return value of repository.isBare() is for any given repository they operate on.

''DirCache read(), lock() moved'':  The methods were moved to Repository, to better permit a specific repository implementation to manage how their DirCache should be accessed.

''ObjectLoader getCachedBytes(), getBytes() can throw LargeObjectException'':  If an object is bigger than core.streamFileThreshold, it cannot be accessed as a contiguous array of bytes.  LargeObjectException is thrown from the accessors, and applications must use openStream() or copyTo() on the ObjectLoader to obtain the object's contents.  By default core.streamFileThreshold is 1 MiB, but is capped at no more than 1/4 of the JVM maximum heap size.

''RevObject.equals() by identity check replaced by AnyObjectId.equals() by value comparison'': equals() was not consistent across AnyObjectId's class hierarchy which defines value object semantics by using instanceof type check and value comparison while RevObject which is a subclass of AnyObjectId overrode equals() with identity check semantics. This broke the symmetry and transititivity properties of the equals contract defined in javadoc for Object.equals(). To fix that RevObject.equals() was backed out and AnyObjectId.equals() made final. Applications that were depending on reference equality of RevObjects should now use == and not .equals().