fix(tree): remove Tree.cache - use IndexFile.write_tree() instead

For more information, see CHANGES.rst

Fixes #369

Author: Byron

Diff for: doc/source/changes.rst

@@ -9,13 +9,14 @@ Changelog
   used previously usually fails to release its resources (i.e. file handles), which can lead to problems when working
   with large repositories.
 * CRITICAL: fixed incorrect `Commit` object serialization when authored or commit date had timezones which were not
-  divisable by 3600 seconds. This would happen if the timezone was something like `+0530` for instance.
+  divisiblej by 3600 seconds. This would happen if the timezone was something like `+0530` for instance.
 * A list of all additional fixes can be found `on github <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v1.0.2+-+Fixes%22+is%3Aclosed>`_
+* CRITICAL: `Tree.cache` was removed without replacement. It is technically impossible to change individual trees and expect their serialization results to be consistent with what *git* expects. Instead, use the `IndexFile` facilities to adjust the content of the staging area, and write it out to the respective tree objects using `IndexFile.write_tree()` instead.
 
 1.0.1 - Fixes
 =============
 
-* A list of all issues can be found `on github <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v1.0.1+-+Fixes%22+is%3Aclosed>`_  
+* A list of all issues can be found `on github <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v1.0.1+-+Fixes%22+is%3Aclosed>`_
 
 1.0.0 - Notes
 =============
@@ -29,18 +30,18 @@ It follows the `semantic version scheme <http://semver.org>`_, and thus will not
 * `IndexFile.add()` will now write the index without any extension data by default. However, you may override this behaviour with the new `write_extension_data` keyword argument.
 
   - Renamed `ignore_tree_extension_data` keyword argument in `IndexFile.write(...)` to `ignore_extension_data`
-* If the git command executed during `Remote.push(...)|fetch(...)` returns with an non-zero exit code and GitPython didn't 
+* If the git command executed during `Remote.push(...)|fetch(...)` returns with an non-zero exit code and GitPython didn't
   obtain any head-information, the corresponding `GitCommandError` will be raised. This may break previous code which expected
-  these operations to never raise. However, that behavious is undesirable as it would effectively hide the fact that there 
+  these operations to never raise. However, that behavious is undesirable as it would effectively hide the fact that there
   was an error. See `this issue <https://github.com/gitpython-developers/GitPython/issues/271>`_ for more information.
 
 * If the git executable can't be found in the PATH or at the path provided by `GIT_PYTHON_GIT_EXECUTABLE`, this is made
   obvious by throwing `GitCommandNotFound`, both on unix and on windows.
 
   - Those who support **GUI on windows** will now have to set `git.Git.USE_SHELL = True` to get the previous behaviour.
-    
-* A list of all issues can be found `on github <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v0.3.7+-+Fixes%22+is%3Aclosed>`_  
-  
+
+* A list of all issues can be found `on github <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v0.3.7+-+Fixes%22+is%3Aclosed>`_
+
 
 0.3.6 - Features
 ================
@@ -54,7 +55,7 @@ It follows the `semantic version scheme <http://semver.org>`_, and thus will not
   * As `rev_parse` will now throw `BadName` as well as `BadObject`, client code will have to catch both exception types.
   * Repo.working_tree_dir now returns None if it is bare. Previously it raised AssertionError.
   * IndexFile.add() previously raised AssertionError when paths where used with bare repository, now it raises InvalidGitRepositoryError
-  
+
 * Added `Repo.merge_base()` implementation. See the `respective issue on github <https://github.com/gitpython-developers/GitPython/issues/169>`_
 * `[include]` sections in git configuration files are now respected
 * Added `GitConfigParser.rename_section()`
@@ -89,7 +90,7 @@ It follows the `semantic version scheme <http://semver.org>`_, and thus will not
 =======
 * `Fix for #207 <https://github.com/gitpython-developers/GitPython/issues/207>`_
 
-0.3.2 
+0.3.2
 =====
 
 * Release of most recent version as non-RC build, just to allow pip to install the latest version right away.
@@ -100,13 +101,13 @@ It follows the `semantic version scheme <http://semver.org>`_, and thus will not
 * **git** command wrapper
 
  * Added ``version_info`` property which returns a tuple of integers representing the installed git version.
- 
+
  * Added GIT_PYTHON_GIT_EXECUTABLE environment variable, which can be used to set the desired git executable to be used. despite of what would be found in the path.
- 
+
 * **Blob** Type
 
  * Added mode constants to ease the manual creation of blobs
- 
+
 * **IterableList**
 
  * Added __contains__ and __delitem__ methods
@@ -118,8 +119,8 @@ It follows the `semantic version scheme <http://semver.org>`_, and thus will not
  * Parsing of tags was improved. Previously some parts of the name could not be parsed properly.
  * The rev-parse pure python implementation now handles branches correctly if they look like hexadecimal sha's.
  * GIT_PYTHON_TRACE is now set on class level of the Git type, previously it was a module level global variable.
- * GIT_PYTHON_GIT_EXECUTABLE is a class level variable as well. 
- 
+ * GIT_PYTHON_GIT_EXECUTABLE is a class level variable as well.
+
 
 0.3.1 Beta 2
 ============
@@ -128,7 +129,7 @@ It follows the `semantic version scheme <http://semver.org>`_, and thus will not
  * New types: ``RefLog`` and ``RefLogEntry``
  * Reflog is maintained automatically when creating references and deleting them
  * Non-intrusive changes to ``SymbolicReference``, these don't require your code to change. They allow to append messages to the reflog.
- 
+
      * ``abspath`` property added, similar to ``abspath`` of Object instances
      * ``log()`` method added
      * ``log_append(...)`` method added
@@ -137,19 +138,19 @@ It follows the `semantic version scheme <http://semver.org>`_, and thus will not
      * ``set_object(...)`` method added (reflog support)
 
  * **Intrusive Changes** to ``Head`` type
- 
+
   * ``create(...)`` method now supports the reflog, but will not raise ``GitCommandError`` anymore as it is a pure python implementation now. Instead, it raises ``OSError``.
-  
+
  * **Intrusive Changes** to ``Repo`` type
- 
+
   * ``create_head(...)`` method does not support kwargs anymore, instead it supports a logmsg parameter
-     
+
 * Repo.rev_parse now supports the [ref]@{n} syntax, where *n* is the number of steps to look into the reference's past
 
 * **BugFixes**
 
     * Removed incorrect ORIG_HEAD handling
- 
+
 * **Flattened directory** structure to make development more convenient.
 
  * .. note:: This alters the way projects using git-python as a submodule have to adjust their sys.path to be able to import git-python successfully.
@@ -178,7 +179,7 @@ Renamed Modules
   * git.utils -> git.util
   * git.errors -> git.exc
   * git.objects.utils -> git.objects.util
-  
+
 General
 -------
 * Object instances, and everything derived from it, now use binary sha's internally. The 'sha' member was removed, in favor of the 'binsha' member. An 'hexsha' property is available for convenient conversions. They may only be initialized using their binary shas, reference names or revision specs are not allowed anymore.
@@ -189,7 +190,7 @@ General
 * IndexFile.get_entries_key was renamed to entry_key
 * IndexFile.write_tree: removed missing_ok keyword, its always True now. Instead of raising GitCommandError it raises UnmergedEntriesError. This is required as the pure-python implementation doesn't support the missing_ok keyword yet.
 * diff.Diff.null_hex_sha renamed to NULL_HEX_SHA, to be conforming with the naming in the Object base class
- 
+
 
 0.2 Beta 2
 ===========
@@ -200,56 +201,56 @@ General
 =====
 General
 -------
-* file mode in Tree, Blob and Diff objects now is an int compatible to definintiions 
-  in the stat module, allowing you to query whether individual user, group and other 
+* file mode in Tree, Blob and Diff objects now is an int compatible to definintiions
+  in the stat module, allowing you to query whether individual user, group and other
   read, write and execute bits are set.
 * Adjusted class hierarchy to generally allow comparison and hash for Objects and Refs
-* Improved Tag object which now is a Ref that may contain a tag object with additional 
+* Improved Tag object which now is a Ref that may contain a tag object with additional
   Information
-* id_abbrev method has been removed as it could not assure the returned short SHA's 
+* id_abbrev method has been removed as it could not assure the returned short SHA's
   where unique
 * removed basename method from Objects with path's as it replicated features of os.path
-* from_string and list_from_string methods are now private and were renamed to 
-  _from_string  and _list_from_string respectively. As part of the private API, they 
+* from_string and list_from_string methods are now private and were renamed to
+  _from_string  and _list_from_string respectively. As part of the private API, they
   may change without prior notice.
 * Renamed all find_all methods to list_items - this method is part of the Iterable interface
   that also provides a more efficients and more responsive iter_items method
 * All dates, like authored_date and committer_date, are stored as seconds since epoc
-  to consume less memory - they can be converted using time.gmtime in a more suitable 
+  to consume less memory - they can be converted using time.gmtime in a more suitable
   presentation format if needed.
-* Named method parameters changed on a wide scale to unify their use. Now git specific 
+* Named method parameters changed on a wide scale to unify their use. Now git specific
   terms are used everywhere, such as "Reference" ( ref ) and "Revision" ( rev ).
   Prevously multiple terms where used making it harder to know which type was allowed
   or not.
 * Unified diff interface to allow easy diffing between trees, trees and index, trees
   and working tree, index and working tree, trees and index. This closely follows
   the git-diff capabilities.
-* Git.execute does not take the with_raw_output option anymore. It was not used 
+* Git.execute does not take the with_raw_output option anymore. It was not used
   by anyone within the project and False by default.
-  
+
 
 Item Iteration
 --------------
-* Previously one would return and process multiple items as list only which can 
-  hurt performance and memory consumption and reduce response times. 
-  iter_items method provide an iterator that will return items on demand as parsed 
+* Previously one would return and process multiple items as list only which can
+  hurt performance and memory consumption and reduce response times.
+  iter_items method provide an iterator that will return items on demand as parsed
   from a stream. This way any amount of objects can be handled.
 * list_items method returns IterableList allowing to access list members by name
-  
+
 objects Package
 ----------------
-* blob, tree, tag and commit module have been moved to new objects package. This should 
-  not affect you though unless you explicitly imported individual objects. If you just 
+* blob, tree, tag and commit module have been moved to new objects package. This should
+  not affect you though unless you explicitly imported individual objects. If you just
   used the git package, names did not change.
-  
+
 Blob
 ----
 * former 'name' member renamed to path as it suits the actual data better
 
 GitCommand
 -----------
-* git.subcommand call scheme now prunes out None from the argument list, allowing 
-  to be called more confortably as None can never be a valid to the git command 
+* git.subcommand call scheme now prunes out None from the argument list, allowing
+  to be called more confortably as None can never be a valid to the git command
   if converted to a string.
 * Renamed 'git_dir' attribute to 'working_dir' which is exactly how it is used
 
@@ -263,43 +264,43 @@ Config
 * The git configuration can now be read and manipulated directly from within python
   using the GitConfigParser
 * Repo.config_reader() returns a read-only parser
-* Repo.config_writer() returns a read-write parser 
- 
+* Repo.config_writer() returns a read-write parser
+
 Diff
 ----
 * Members a a_commit and b_commit renamed to a_blob and b_blob - they are populated
   with Blob objects if possible
 * Members a_path and b_path removed as this information is kept in the blobs
-* Diffs are now returned as DiffIndex allowing to more quickly find the kind of 
+* Diffs are now returned as DiffIndex allowing to more quickly find the kind of
   diffs you are interested in
-  
+
 Diffing
 -------
-* Commit and Tree objects now support diffing natively with a common interface to 
+* Commit and Tree objects now support diffing natively with a common interface to
   compare agains other Commits or Trees, against the working tree or against the index.
 
 Index
 -----
 * A new Index class allows to read and write index files directly, and to perform
   simple two and three way merges based on an arbitrary index.
-  
+
 Referernces
 ------------
 * References are object that point to a Commit
 * SymbolicReference are a pointer to a Reference Object, which itself points to a specific
   Commit
-* They will dynmically retrieve their object at the time of query to assure the information 
-  is actual. Recently objects would be cached, hence ref object not be safely kept 
+* They will dynmically retrieve their object at the time of query to assure the information
+  is actual. Recently objects would be cached, hence ref object not be safely kept
   persistent.
-  
+
 Repo
 ----
 * Moved blame method from Blob to repo as it appeared to belong there much more.
-* active_branch method now returns a Head object instead of a string with the name 
+* active_branch method now returns a Head object instead of a string with the name
   of the active branch.
 * tree method now requires a Ref instance as input and defaults to the active_branche
   instead of master
-* is_dirty now takes additional arguments allowing fine-grained control about what is 
+* is_dirty now takes additional arguments allowing fine-grained control about what is
   considered dirty
 * Removed the following methods:
 
@@ -311,15 +312,15 @@ Repo
   - 'create' method which equals the 'init' method's functionality
   - 'diff' - it returned a mere string which still had to be parsed
   - 'commit_diff' - moved to Commit, Tree and Diff types respectively
-  
+
 * Renamed the following methods:
 
   - commits to iter_commits to improve the performance, adjusted signature
   - init_bare to init, implying less about the options to be used
   - fork_bare to clone, as it was to represent general clone functionality, but implied
     a bare clone to be more versatile
   - archive_tar_gz and archive_tar and replaced by archive method with different signature
-  
+
 * 'commits' method has no max-count of returned commits anymore, it now behaves  like git-rev-list
 * The following methods and properties were added
 
@@ -330,16 +331,16 @@ Repo
   - 'config_reader' method
   - 'config_writer' method
   - 'bare' property, previously it was a simple attribute that could be written
-  
+
 * Renamed the following attributes
 
   - 'path' is now 'git_dir'
   - 'wd' is now 'working_dir'
-  
+
 * Added attribute
 
   - 'working_tree_dir' which may be None in case of bare repositories
-  
+
 Remote
 ------
 * Added Remote object allowing easy access to remotes
@@ -349,15 +350,15 @@ Remote
 Test Framework
 --------------
 * Added support for common TestCase base class that provides additional functionality
-  to receive repositories tests can also write to. This way, more aspects can be 
+  to receive repositories tests can also write to. This way, more aspects can be
   tested under real-world ( un-mocked ) conditions.
 
 Tree
 ----
 * former 'name' member renamed to path as it suits the actual data better
 * added traverse method allowing to recursively traverse tree items
 * deleted blob method
-* added blobs and trees properties allowing to query the respective items in the 
+* added blobs and trees properties allowing to query the respective items in the
   tree
 * now mimics behaviour of a read-only list instead of a dict to maintain order.
 * content_from_string method is now private and not part of the public API anymore
@@ -496,14 +497,14 @@ Git
 
 * Added support for ``stderr``, ``stdin``, and ``with_status``.
 
-* ``git_dir`` is now optional in the constructor for ``git.Git``.  Git now 
+* ``git_dir`` is now optional in the constructor for ``git.Git``.  Git now
   falls back to ``os.getcwd()`` when git_dir is not specified.
 
-* add a ``with_exceptions`` keyword argument to git commands. 
+* add a ``with_exceptions`` keyword argument to git commands.
   ``GitCommandError`` is raised when the exit status is non-zero.
 
-* add support for a ``GIT_PYTHON_TRACE`` environment variable. 
-  ``GIT_PYTHON_TRACE`` allows us to debug GitPython's usage of git through 
+* add support for a ``GIT_PYTHON_TRACE`` environment variable.
+  ``GIT_PYTHON_TRACE`` allows us to debug GitPython's usage of git through
   the use of an environment variable.
 
 Tree
@@ -519,8 +520,8 @@ Repo
 
 Tree
 ----
-* Corrected problem with ``Tree.__div__`` not working with zero length files.  
-  Removed ``__len__`` override and replaced with size instead. Also made size 
+* Corrected problem with ``Tree.__div__`` not working with zero length files.
+  Removed ``__len__`` override and replaced with size instead. Also made size
   cach properly. This is a breaking change.
 
 0.1.1