docs: add documentation to state differences from the git cli#4605
docs: add documentation to state differences from the git cli#4605pks-t merged 2 commits intolibgit2:masterfrom
Conversation
|
Thanks for this PR! It was one of our takeaways from the recent lbgit2 summit to start such documentation, so this is definitely welcome. We could also extend this document for features not (yet) implemented in libgit2 later |
|
I'm glad you like the PR! Is there anything you would have me add now, or anything related to the structure of the document that you would like changed? |
|
Only in case you feel like adding the feature-comparison I was talking about. Otherwise I'm happy to merge if you've addressed my comments |
|
I don't see any comments? I would also need help identifying all features that are different from the CLI. I can find some, but I doubt I will find them all, however I am happy to start that. |
pks-t
left a comment
There was a problem hiding this comment.
Oh, sorry. Forgot to publish my review
| @@ -0,0 +1,40 @@ | |||
| # Differences from the Git CLI | |||
|
|
|||
| In some instances, the functionality of libgit2 deviates slightly from that of the Git CLI. This can because of technical limitations when developing a library, licensing limitations when converting functionality from the CLI to libgit2, or various other reasons. | |||
There was a problem hiding this comment.
There's a missing word in "This can because".
| @@ -0,0 +1,40 @@ | |||
| # Differences from the Git CLI | |||
There was a problem hiding this comment.
I'd just name this "differences-from-git.md"
| Repository and Workdir Path Reporting | ||
| ------------------------------------- | ||
|
|
||
| When retrieving the absolute path of a repository from the Git CLI, one could expect the output to lool like so: |
There was a problem hiding this comment.
It's nice to document this, but I think this is overly long. Proposal:
"""
When asking Git for the absolute path of a repository via git rev-parse --absolute-git-dir, it will output the path to the ".git" folder without a trailing slash. In contrast to that, the call git_repository_path(repo) will return the path with a trailing slash:
git rev-parse --absolute-git-dir -> /home/user/projects/libgit2/.git
git_repository_path(repo) -> /home/user/projects/libgit2/.git/
The same difference exists when listing worktrees:
git worktree list -> /home/user/projects/libgit2
git_repository_workdir(repo) -> /home/user/projects/libgit2/
"""
There was a problem hiding this comment.
Nice, this is much more concise. I didn't know how much detail I should add so I was winging it. I like this better.
|
I want to add more to this document but it's been a while since I was in |
|
It's a good start, so I just went ahead and merged it. We can (and probably should) just amend this document as time goes by. Thanks! |
Started potential documentation to list differences in functionality from the of the Git CLI. If anyone has other things they would like to include, such as missing functionality, or if they would like wording changed please let me know.
This is in response to issue #4583