Zettlr: Feature: Collaborative Editing with Git

[max-l]

Firstly, I'd like to thank you @nathanlesage for this awesome project. For some reason I just discovered it, and I'm really excited about it !

The problem of getting non tech user to produce and maintain content that integrate into sophisticated front ends is not yet solved, which is unfortunate, because 95% of good writers are not techies.

The most flexible/sophisticated/powerful publishing front ends today are Jamstack based : https://jamstack.org/

The problem with JamStack is to get non tech users to produce content for it. They need an editor that they will enjoy using, but that saves in a sane/transparent format (such as markdown). For that content to integrate into a JamStack setup, it almost has to be git, I mean it's the no brainer choice, since practically all JamStack tools are designed with Git it mind. Gatsby is one of the leading JamStack front end: https://www.gatsbyjs.org/

Zettlr has the potential to be liked by non tech users, and finaly get them to abandon obscure formats. To make Zettlr JamStack capable, it only needs git syncinc capability.

A Git backed Zettlr option with a Gatsby front end would be the most badass publishing platform IMO !

Having "transparent" git syncing usable by non techies is key, and it must be designed in a way that makes collaboration easyest, which means that merge conflicts need to be reduced to an absolute minimun.

One way to do this would be to have a branch naming scheme where each user+file has it's own branch, and collaborative branch also be in their own (automatically named) branches.

Here's how I think it could work:

A user configures a "Sync workspace to Git" option (could be github or gitLab, or other...),
that would setup a repo or join an existing repo (ex. the zettlr repo of another user).

Each Zettlr user that joined the repo would have it's own branch, it could be named:

<GitUserId>//<FileName or zettelkasten Id>

Saves would be local, but when "Save to Git" is clicked, a git commit is created, first in a local user+file branch, which gets pushed to the remote repo everytie a commit is added.

The user would have a "Publish" button, that would cause a tag to be added to the user+file branch, and once that happens, a hook on the remote repo that watches all user branches would automatically merge it to a "staging" branch (the default staging branch could be master).

When a user edits another user's file, another kind of branch would be created, derived from
the owner's branch, it could be named like:

<OwnerGitUserId>+<CollaboratingGitUserId>//<FileName or zettelkasten Id>

Collaborative branches would not be merged to staging, the owner would have to accept the changes, which would pull the collaboration branch, then tag it to have it merge to staging. To reduce confusion, colloborative branch should be removed (or hidden) from user environments once merged.

I say this other thread about git syncinc, but I thought that "collaborative editing with git" has a broader scope and warrented it's onw issue : https://github.com/Zettlr/Zettlr/issues/224

[nathanlesage]

Sounds interesting, although I don't know why we would need such a complicated branching system. If I'm not mistaken, a standard repository with only a master branch would suffice for most cases.

Use case example: Collaborative writing on a research project

1. One user creates a GitHub repository and clones it to her computer.
2. Other do the same
3. Zettlr simply displays "Hey, here's a Git directory!"
4. Users pull the repository from time to time (e.g. by right-clicking the directory)
5. Once users are ready they create a "snapshot" with a single click (that is: Add all files -> commit -> pull request)
6. The owner can accept this one and merge. In the meantime the users can create more commits, which will be merged as well.
7. In case of conflicts, the built-in Git conflict merging syntax could be highlighted.

[max-l]

The use case I'm thinking of is the ability for users to publish individual files, while having other files that are in draft, and some of them never to be published.

Now that I'm rethinking this I realize the approach I proposed has problems and doesn't actualy work (for a few reasons).

Perhaps things can be much simpler if the publised|unpublished status is kept inside the files, as meta data ex: [comment]:PUBLISHED

This has the advantage over using git to "unpublish" files, since using "git delete" would bring much complexity.

I think that this way, what you suggested would actually work and be an order of magnitude simpler that what I proposed !

[nathanlesage]

Yeah, I see what you mean, but again I would opt for a directory-based approach: You have one directory in which you basically keep all your drafts, and backup them using Git (for example, not necessarily), and once they go in review mode, you move them to the repository-directory and commit them as you'd do with any other Git files! This way the amount of work on my side is bearable while users retain the full control of their files (i.e. they have specific directories in which they know other people can collaborate). I'll keep it on the agenda!

[max-l]

A meta data approach would actually require no new functionality in Zettlr,
It would be the consumer (ex. a Gatsby plugin) that would filter all the files depending on the presence of a certain keyword or pattern in a markdown comment (ex, every file that contains [comment]:PUBLISHED) gets publish.

Now that I think of it, the Gatsby plugin could also be parametrize with a file matching pattern, like you propose. All of this done outside of Zettlr.

It's almost as if this discussion doesn't belong here in Zettlr issue ! ;-) But the discussion might serve as a brainstorming on requirements for Git sync feature.

BTW, there is already a Gatsby plugin that could do a file pattern based extraction from an arbitrary GIT source: https://www.gatsbyjs.org/packages/gatsby-source-git/

So the only piece missing for authoring with Zettlr in a JamStack setup is the GIT sync feature !

[nathanlesage]

… sooo what I would need to do is add some fancy buttons to automate those git commands? 😝

[max-l]

Yes, there are pretty solid libraries that can do the interfacing with GIT:

1. https://www.nodegit.org/
2. https://github.com/steveukx/git-js

I haven't actualy tried them, but it seems that nodegit (1) is more advantageous, and easy to package in Zettlr, without requiring the user to install git. I think simplicity is a must because the "save to git" is for non tech users, "git capable" users will likely have git already installed and prefer to just call git directly from the command line anyways.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically closed due to inactivity. If you believe that this issue is relevant for many users and should not be closed, feel free to comment so that the admins will be notified.