Add missing Repo.tracked_files convenience property#2121
Add missing Repo.tracked_files convenience property#2121huyhoang171106 wants to merge 2 commits intogitpython-developers:mainfrom
Repo.tracked_files convenience property#2121Conversation
Signed-off-by: Nguyen Huy Hoang <181364121+huyhoang171106@users.noreply.github.com>
Signed-off-by: Nguyen Huy Hoang <181364121+huyhoang171106@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a missing symmetry in the Repo API by introducing a tracked_files convenience property (complementing untracked_files) and documenting it at a high level in the project README.
Changes:
- Add
Repo.tracked_filesproperty to list currently tracked files. - Document availability of both
Repo.untracked_filesandRepo.tracked_filesinREADME.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
git/repo/base.py |
Introduces Repo.tracked_files implemented via git ls-files. |
README.md |
Mentions the new Repo.tracked_files convenience property alongside untracked_files. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @property | ||
| def tracked_files(self) -> List[str]: | ||
| """Files currently tracked by git.""" | ||
| return self.git.ls_files().splitlines() |
There was a problem hiding this comment.
This new public convenience property should have test coverage similar to Repo.untracked_files (see test_repo.py::test_untracked_files). Please add a test that tracked_files returns expected tracked paths (ideally including spaces/unicode), so parsing/quoting regressions are caught.
| return self.git.ls_files().splitlines() | |
| # Use NUL-separated output to safely handle filenames with whitespace, | |
| # newlines, and other special characters. | |
| output = self.git.ls_files("-z") | |
| if not output: | |
| return [] | |
| return output.rstrip("\0").split("\0") |
| @property | ||
| def tracked_files(self) -> List[str]: | ||
| """Files currently tracked by git.""" | ||
| return self.git.ls_files().splitlines() |
There was a problem hiding this comment.
tracked_files parses git ls-files output by splitting on newlines. This will mis-handle valid pathnames that contain newlines, and can also mis-parse/return quoted or escaped paths when Git applies core.quotepath. Consider calling ls-files with NUL-termination (e.g., -z) and splitting on \0 (dropping the trailing empty entry) to get an unambiguous list of paths.
| return self.git.ls_files().splitlines() | |
| output = self.git.ls_files("-z") | |
| if not output: | |
| return [] | |
| return output.rstrip("\0").split("\0") |
|
|
||
| @property | ||
| def tracked_files(self) -> List[str]: | ||
| """Files currently tracked by git.""" |
There was a problem hiding this comment.
The docstring for tracked_files is much less informative than untracked_files and will be surfaced in the generated API reference. It would be helpful to document what the paths are relative to, and add a note that the property is expensive/no-cache (similar to untracked_files) so callers don’t accidentally use it in tight loops.
| """Files currently tracked by git.""" | |
| """List of files currently tracked by Git. | |
| The returned paths are relative to the repository's working tree directory. | |
| .. note:: | |
| This property calls out to ``git ls-files`` every time it is accessed | |
| and does not cache results. Avoid calling it in tight loops or other | |
| performance-sensitive code paths. | |
| """ |
Summary
The issue is not a runtime defect, but an API/documentation gap:
Repoexposesuntracked_filesbut has no symmetrictracked_filesproperty, which makes common usage inconsistent and discoverability poor. Users currently need to know and call plumbing manually (e.g.,repo.git.ls_files()), and this is not clearly documented in the API reference.Files changed
git/repo/base.py(modified)README.md(modified)Testing
Closes #857