docs: add doc comparing jj to Sapling (#1708)

[martinvonz]

Checklist

If applicable:

• I have updated CHANGELOG.md
• I have updated the documentation (README.md, docs/, demos/)
• I have updated the config schema (src/config-schema.json)
• I have added tests to cover my changes

[PhilipMetzger]

LGTM, but it would be valuable if a Meta employee also took a look at it.

[quark-zju]

Mostly look good to me. There are some future plans that might count as noticeable differences but I think it's fine not documenting them until they are available:

• Sapling might integrate with the virtual filesystem, EdenFS, and indirectly watchman and buck2 (i.e. buck2 can check file content hashes without materializing them on the filesystem). That might justify why it does not co-exist in a same git checkout (since git does not integrate with EdenFS).
• The underlying storage is different. Sapling mainly uses IndexedLog (and its variants RotateLog, and ZStore) so .sl inode count is bounded. As a trade-off Sapling uses file locking and might not work well with NFS (although EdenFS technically can expose its Thrift RPC over the network for remote use-cases). It's a different trade-off from jj. Although right now it's mostly libgit2 and Sapling does not yet use its internal storage library yet.

[zzl0]

LGTM overall. Just two minor comments.

[martinvonz]

Mostly look good to me. There are some future plans that might count as noticeable differences but I think it's fine not documenting them until they are available:

Thanks for reviewing! Yes, I think it's better to document that once it's done. Feel free to send a PR when it is.

• Sapling might integrate with the virtual filesystem, EdenFS, and indirectly watchman and buck2 (i.e. buck2 can check file content hashes without materializing them on the filesystem). That might justify why it does not co-exist in a same git checkout (since git does not integrate with EdenFS).

That actually sounds similar to what we're thinking of doing with jj at Google. I hope we'll be able to do that by replacing the working copy implementation (it's not currently a trait, but it will be soon). So we'll have the default working-copy implementation, which is used outside of Google, and we'll have a custom CitC-aware implementation internally. The right working-copy implementation will be loaded depending on the repo, just like we load the right commit backend etc. So maybe the main difference will be that your VFS-integration will be open-sourced.

• The underlying storage is different. Sapling mainly uses IndexedLog (and its variants RotateLog, and ZStore) so .sl inode count is bounded. As a trade-off Sapling uses file locking and might not work well with NFS (although EdenFS technically can expose its Thrift RPC over the network for remote use-cases). It's a different trade-off from jj. Although right now it's mostly libgit2 and Sapling does not yet use its internal storage library yet.

Ah, that's a good point. I think it's probably too rare that users care about NFS support that it's worth mentioning.

[strager]

If jj supports Git tags, you could mention that Sapling does not support Git tags.

[martinvonz]

If jj supports Git tags, you could mention that Sapling does not support Git tags.

Thanks, but jj has very limited support (you can see and specify revisions by tag name, but you can't create tags), so I don't think it's worth mentioning.