Include TagObject in git.types.Tree_ish by EliahKagan · Pull Request #1878 · gitpython-developers/GitPython (original) (raw)

The Tree_ish union omitted TagObject, whose instances are only sometimes tree-ish, and unlike Commit_ish before #1859, it is not inherently a bug to define Tree_ish this way.

However, this Tree_ish type actually has only one use in GitPython (which was also the case before the changes in #1859): as, itself, an alternative in the union used to annotate the rev parameter of the Repo.tree method (whose other alternatives are str and None). A TagObject may be passed, and if it points to a tree or commit then that will be resolved. Just to avoid a mypy error, code doing that would (before this change) have to convert it to str first.

That annotation should be improved, and the best way to do it is to keep it written the same way but change the definition of Tree_ish in git.types to include TagObject. The reason is that doing so alleviates a major unintuitive aspect of the relationship between the Commit_ish and Tree_ish types: Commit_ish was broader than everything commit-ish, while Tree_ish was narrower than everything tree-ish.

I had not considered making this change in #1859 because I didn't want to modify Tree_ish unnecessarily, and its definition was not inherently a bug. However, the change to Commit_ish is sufficiently large (though it only affects static typing) that a change to Tree_ish to make them coherent and intuitive may be justified.

This pull request changes Tree_ish so that, in addition to its Commit and Tree alternatives, it also includes TagObject. This also updates and simplifies its docstring accordingly, bringing it in line with that of Commit_ish which is already defined with the same kind of breadth, and further revises both docstrings to more explicitly clarify when tags are tree-ish or commit-ish and when they are not.

Notes

This is related to #1859 (comment).

This does not change the separate nonpublic Treeish type defined in git.index.base (and named with no underscore), which omits TagObject but includes bytes and str, and which is used to annotate parameters of the IndexFile.from_tree and IndexFile.merge_tree methods. Changes there may be valuable, but the goal here is just to build narrowly on #1859 to address a shortcoming of the revisions to git.types.