René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Commit_ish is much broader than commit-ish","articleBody":"In git, if I understand correctly, a *commit-ish* is a git object from which a commit can be reached by dereferencing it zero or more times, which is to say that all commits are commit-ish, some tag objects are commit-ish--those that, through (possibly repeated) dereferencing, eventually reach a commit--and no other types of git objects are ever commit-ish.\r\n\r\nAs [gitglossary(7) says](https://git-scm.com/docs/gitglossary#def_commit-ish):\r\n\r\n\u003e #### commit-ish (also committish)\r\n\u003e\r\n\u003e A [commit object](https://git-scm.com/docs/gitglossary#def_commit_object) or an [object](https://git-scm.com/docs/gitglossary#def_object) that can be recursively [dereferenced](https://git-scm.com/docs/gitglossary#def_dereference) to a commit object. The following are all commit-ishes: a commit object, a [tag object](https://git-scm.com/docs/gitglossary#def_tag_object) that points to a commit object, a tag object that points to a tag object that points to a commit object, etc.\r\n\r\nTherefore, *all* instances of GitPython's `Commit` class, and *some* instances of GitPython's `TagObject` class, encapsulate git objects that are actually commit-ish.\r\n\r\nBut GitPython has a `Commit_ish` union type in the `git.types` module, and that `Commit_ish` type is considerably broader:\r\n\r\nhttps://github.com/gitpython-developers/GitPython/blob/b2c3d8b72301dc4723e83de676fd7086d5c3c381/git/types.py#L53\r\n\r\nThese four classes are the GitPython classes whose instances encapsulate any of the [four types of git objects](https://git-scm.com/docs/gitglossary#def_object_type) (of which blobs and trees are never actually commit-ish):\r\n\r\n\u003e #### object type\r\n\u003e\r\n\u003e One of the identifiers \"[commit](https://git-scm.com/docs/gitglossary#def_commit_object)\", \"[tree](https://git-scm.com/docs/gitglossary#def_tree_object)\", \"[tag](https://git-scm.com/docs/gitglossary#def_tag_object)\" or \"[blob](https://git-scm.com/docs/gitglossary#def_blob_object)\" describing the type of an [object](https://git-scm.com/docs/gitglossary#def_object).\r\n\r\nGitPython uses its `Commit_ish` type in accordance with this much broader concept, at least some of the time and possibly always. For example, `Commit_ish` is given as the return type of `Object.new`:\r\n\r\nhttps://github.com/gitpython-developers/GitPython/blob/b2c3d8b72301dc4723e83de676fd7086d5c3c381/git/objects/base.py#L77-L78\r\n\r\n`Commit_ish` cannot simply be replaced by `Object` because GitPython's `Object` class is also, through `IndexObject`, a superclass of `Submodule` (and the `RootModule` subclass of `Submodule`):\r\n\r\nhttps://github.com/gitpython-developers/GitPython/blob/b2c3d8b72301dc4723e83de676fd7086d5c3c381/git/objects/submodule/base.py#L82\r\n\r\nhttps://github.com/gitpython-developers/GitPython/blob/b2c3d8b72301dc4723e83de676fd7086d5c3c381/git/objects/submodule/base.py#L87-L88\r\n\r\nhttps://github.com/gitpython-developers/GitPython/blob/b2c3d8b72301dc4723e83de676fd7086d5c3c381/git/objects/submodule/base.py#L100-L101\r\n\r\nHowever, elsewhere in GitPython, `Commit_ish` is used where it seems only a commit is intended to be allowed, though it is unclear if this is unintentional, intentional but only to allow type checkers to allow some code that can only reasonably be checked at runtime, or intentional for some other reason. For example, the `Repo.commit` method, when called with one argument, looks up a commit in the repository it represents from a `Commit_ish` or string, and returns the commit it finds as a `Commit`:\r\n\r\nhttps://github.com/gitpython-developers/GitPython/blob/b2c3d8b72301dc4723e83de676fd7086d5c3c381/git/repo/base.py#L698\r\n\r\nThis leads to a situation where one can write code that type checkers allow and that may appear intended to work, but that always fails, and in a way that may be unclear to users less familiar with git concepts:\r\n\r\n```text\r\n\u003e\u003e\u003e import git\r\n\u003e\u003e\u003e repo = git.Repo()\r\n\u003e\u003e\u003e tree = repo.tree()\r\n\u003e\u003e\u003e repo.commit(tree)\r\nTraceback (most recent call last):\r\n  File \"\u003cstdin\u003e\", line 1, in \u003cmodule\u003e\r\n  File \"C:\\Users\\ek\\source\\repos\\GitPython\\git\\repo\\base.py\", line 709, in commit\r\n    return self.rev_parse(str(rev) + \"^0\")\r\n           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n  File \"C:\\Users\\ek\\source\\repos\\GitPython\\git\\repo\\fun.py\", line 379, in rev_parse\r\n    obj = to_commit(obj)\r\n          ^^^^^^^^^^^^^^\r\n  File \"C:\\Users\\ek\\source\\repos\\GitPython\\git\\repo\\fun.py\", line 221, in to_commit\r\n    raise ValueError(\"Cannot convert object %r to type commit\" % obj)\r\nValueError: Cannot convert object \u003cgit.Tree \"d5538cc6cc8839ccb0168baf9f98aebcedfd9c2c\"\u003e to type commit\r\n```\r\n\r\nAn argument that this specific situation with `Repo.commit` is not a typing bug is that this operation is fundamentally one that can only be checked at runtime in some cases. After all, an argument of type `str` is also allowed and it cannot known until runtime what object a string happens to name. Even so, the method docstring should possibly be expanded to clarify this issue. Or perhaps if the situation with `Commit_ish` is improved, then the potential for confusion will go away.\r\n\r\nOne way to improve this situation is to clearly document it in a docstring for the `Commit_ish` type. But if possible it seems to me that more should be done:\r\n\r\n- If known, the reason for the current situation should be stated there.\r\n- Its relationship to other types should be clarified where otherwise confusing. For example, `Object` may benefit from greater clarity about what it ideally represents (git objects) versus the entirety of what it represents (that an `Object` can also be a `Submodule`), and the way that `Tree_ish` is narrower than all tree-ish git objects while `Commit_ish` is broader than all commit-ish git objects can be noted in one of their docstrings.\r\n- Maybe `Commit_ish` should be deprecated and one or more new types introduced, replacing all uses of it in GitPython.\r\n\r\nIf I am making a fundamental mistake about git concepts here, and GitPython's `Commit_ish` has a closer and more intuitive relationship to commit-ish git objects than I think it does, then I apologize.\r\n\r\nI have not figured out very much from GitPython's revision history what the reason for defining `Commit_ish` as it is currently defined is, or alternatively why this union of all four actual git object types was introduced with the narrower-seeming name `Commit_ish`. However, the `Commit_ish` type was introduced in 82b131c (#1282), where the annotations it was used to replace had listed all four types `Commit`, `TagObject`, `Tree`, and `Blob` as explicit alternatives.","author":{"url":"https://github.com/EliahKagan","@type":"Person","name":"EliahKagan"},"datePublished":"2024-03-04T21:16:42.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":4},"url":"https://github.com/1858/GitPython/issues/1858"}