Windows and backslashes in paths

[eht16]

Using libgit2 0.22.1 on Windows, I noticed git_tree_entry_bypath() seems to require foward slashes as path seperator while git_repository_open_ext() accepts a path to the repository with backslashes happily.

I understand paths within a repository are internally handled with forward slashes only. But I'm wondering how to get around the issue.
Should libgit2 normalize the path it receives in git_tree_entry_bypath() or is it the at the caller to pass in relative path with forward slashes already? In case of the latter case, maybe the docs should mention this to make it more clear.

[ethomson]

Should libgit2 normalize the path it receives in git_tree_entry_bypath() or is it the at the caller to pass in relative path with forward slashes already? In case of the latter case, maybe the docs should mention this to make it more clear.

As you point out - there are two separate concepts: filesystem paths can be specified in the manner that the local system accepts. (Windows accepts both forward and backslashes in Win32 calls, generally speaking.) Repository paths (in the index, trees, etc) are always represented in Git semantics and thus have forward slashes.

I can see how this might be confusing, and certainly documentation is very important. Would you be interested in helping to clarify this a bit?

[eht16]

diff --git a/include/git2/tree.h b/include/git2/tree.h
index 550a448..c74cbdf 100644
--- a/include/git2/tree.h
+++ b/include/git2/tree.h
@@ -136,7 +136,7 @@ GIT_EXTERN(const git_tree_entry *) git_tree_entry_byid(
  *
  * @param out Pointer where to store the tree entry
  * @param root Previously loaded tree which is the root of the relative path
- * @param path Path to the contained entry
+ * @param path Path to the contained entry (repository path with forward slashes)
  * @return 0 on success; GIT_ENOTFOUND if the path does not exist
  */
 GIT_EXTERN(int) git_tree_entry_bypath(

maybe something like this.
I don't know the whole libgit2 API, so I cannot say which other functions might deserve such a hint as well.

[carlosmn]

This is a library-wide thing, Git data structures use a slash as a path separator and it´s not specific to any particular function and it affects input as well as output.

This feels like something we'd want to make explicit as part of some general document like the README. We already have some of this in CONVENTIONS.md though those are mostly written for people who are writing library code rather than using it.

[linquize]

If you pass \ to libgit2, NOT all functions are guaranteed to work properly.
So you need to normalize to '/' before passing to libgit2.

[ethomson]

If there's a function that takes a local path and fails to accept \ as a delimiter n Windows, please file a bug.

[eht16]

I agree CONVENTIONS.md might be targeted a bit too much to library developers, still it won't hurt to mention it.
But maybe the docs could need a general intro page mentioning general API usage hints as well as possible caveats.

Before you ask, I don't volunteer for this :). I really don't know libgit2 well enough to write such a page.