Git Sync: scope the design before implementation

[amirrza777]

Steffen @szschaler asked me to pick this up next. This was previously discussed only by email and never scoped as an issue or designed, so before writing any code I want to nail down the actual requirements.

Current state, for context: there is no git integration anywhere in the codebase today (no JGit dependency, no git CLI usage). Project files are stored as flat rows in a Postgres table (path, content, file type, and a simple integer version counter used for optimistic-concurrency conflict detection in the real-time collaborative editing over WebSocket), not as an actual filesystem or any kind of versioned history. The only export mechanism that exists is the recent "Download as zip" button in the file explorer.

Questions before I start:

1. Direction: should this push a project out to an external git repo, pull an existing git repo in as a new project, or support full two-way sync? These are very different amounts of work and different failure modes.

2. Granularity: does every save become a commit automatically, or is there an explicit "commit and push" action the user triggers? If automatic, what determines a commit boundary (every WebSocket save is a very fine grain), and what commit message/author gets used?

3. Credentials: where would a user's git remote credentials (personal access token or SSH key) be stored? Per-user, per-project? This has real security implications I want to get right from the start rather than bolt on later.

4. Conflict handling: projects support simultaneous multi-user editing today. If the external repo changes (e.g., someone pushes directly) while the project is also being edited in the workbench, how should that be reconciled? Last-write-wins, explicit merge UI, something else?

5. Scope: does this need to work with any git host (self-hosted, GitLab, Bitbucket) or is GitHub specifically the target for now?

6. Relatedly: is the goal actual git history (diffable commits a user could inspect with a normal git client), or more like a one-way backup/restore mechanism that happens to use git as the transport? Those imply pretty different architectures.

Happy to write up a concrete design proposal once I know the intended direction on these, rather than guessing and having to redo it.

@nk-coding

[szschaler]

I see two main options here -- a bit like what Overleaf offers:

1. A GitHub integration where a project can be backed by a GitHub repository with an explicitly triggered sync mechanism. Essentially, the MDEO-Cloud project acts as one working repository for the central GitHub repo and every time a sync is triggered, this creates a commit in the GitHub repo, possibly after resolving any conflicts from concurrent changes to the repository. We can choose whether to support branches (MDEO-Cloud project is linked to a particular branch on the GitHub repo) or always sync to the default branch.
2. A Git integration where an MDEO-Cloud server also acts as a -- simple -- Git server and gives access to projects as repositories.

Given that editing of MDEO-Cloud files offline isn't currently supported anyway, I would suggest that Option 1 is the better one for now. I would suggest that a sync includes syncing any result files, but we can discuss...