doc: warn against using init_repository() to open a repository.

[adrien-n]

It turns out this works in some situations but it should be avoided.

[adrien-n]

I forgot to mention I'm also using that PR as a question. Maybe I got that wrong, I'm not sure, but worktrees don't work with init_repository(), or at least not with every flag or combination of flags.

[jdavid]

I don't know, we just call git_repository_init_ext; but the comment makes sense to me, and it matches my interpretation of git_repository_init_ext docs:

Create a new Git repository in the given folder with extended controls.

This will initialize a new git repository [...]

https://libgit2.org/docs/reference/main/repository/git_repository_init_ext.html

[adrien-n]

I noticed the issue with some software using pygit2 and started investigating. I think this also applies to libgit2 directly but I haven't fully followed all the code paths and I haven't found the time to reproduce the issue with it only (which is more involved than comparing Repository.('.') and init_repository('.') in a REPL).

I'll also create a similar PR for libgit2's documentation. I think it's worth having the warning in both places since it appears to be an actual real-world issue which may go un-noticed simply because worktree usage is less widespread.