Explain the Git storage repositories

[alensiljak]

I've gone through some of the documentation (notes, examples, docs, readme) but could not really find an explanation.
I'd like to know why is there a Git repository in the "calendars" folder as well as in "calendars/calendar". The one for a collection (calendar) makes sense but I don't really understand what gets written to the "calendars" folder.

There's a rationale for the collections: https://github.com/jelmer/xandikos/blob/master/notes/file-format.rst

A separate but related issue would be a quick hint on the best way to back up the data structure. The repository in the "calendars" and "contacts" are confusing me and I'm not sure what the best way would be to have a backup - either to add git remote repositories and push, or to copy the whole folder structure to a remote location.

I'd like to see these clarifications added to the docs so please suggest a topic and I'll see to submit a pull request.

[jelmer]

The calendars collection can contain items as well, you can upload regular files there with a webdav client. You could create it as just a regular directory, but then you'd lose the versioning. This is why it's also a Git repository.

The other option would be to create "calendars" as a git repository, and just have "calendar" under that as another version subdirectory rather than its own git repository. See #62

[jelmer]

Contributions to clarify this in the docs would be great as well; also happy to expand on that explanation.

In general, I'd be curious what people would find useful. The current system works for me, though the core of Xandikos is very flexible and we could (perhaps just with the right configuration options) easily structure things differently.

[alensiljak]

Thanks for the clarification so far. I find it relatively simple to set up a server. Adding a couple of details to the docs would be useful, from the perspective of a newcomer. If you could add more about the following topics, I would add them somewhere to the documentation.
Also, consolidating the documentation in one place would be paramount.

1. How to run if the package is installed via pip? Adding an entry point in the setup would help, I assume. After installing via pip, Xandikos was not found in the path. Could also be my setup but having this documented would be useful. I find that to be the simplest installation method.
2. What should be backed up from the data directory and how? Having a git repository is useful and could be used to back up individual collections to a remote location. Also, having a copy of the whole dav folder might be used. I know this is individual and flexible but there could be some default recommendation for a simple and effective solution.

I'm setting up a server on an Android phone and the backup is extremely important.

[jelmer]

Installing from pip should install the 'xandikos' script. If that doesn't happen, that'd be a local issue with your pip setup - and best answered with the pip documentation. I'm not sure that documentation for pip would amount to more than just instructions to run "pip install xandikos" (though that would still be include as an option).

With regards to backups, I'd just back up the entire data directory as-is. If you wanted to reduce the amount of space, you could either force xandikos to create bare repositories (so you don't have a copy of each file in the repository as well as in the working tree) or you could manually clone all the repositories (but that's more involved).

[alensiljak]

Installing from pip should install the 'xandikos' script

Thanks! I can confirm this on another device. Great! This is, by far, the simplest installation method.

[jelmer]

Do you feel like this still needs more documentation?

[alensiljak]

Should be enough for now. Thanks!