status-quo docs/writeup/diagrams about how history works, across all commands

[aryairani]

It is hard to explain and understand, but that's all the more reason to do it

[ChrisPenner]

The most confusing thing to recognize is that currently we haven't really exposed users to the difference between causals and namespaces, so all of our commands just refer to namespaces.

This means that a lot of commands should conceptually have separate versions, e.g. move.causal would be distinct from move.namespace; and delete.causal would be distinct from delete.namespace.

So it raises a question for every command related to namespaces, does it act on causals, namespaces, or both?

An example of some inconsistencies would be:

• delete.namespace works at the namespace level, meaning it creates a new causal node with an empty namespace, appending to the history rather than deleting it.
• move.namespace works at the causal level, meaning it will move the entire causal history from one path to another, replacing the src with an empty causal (which is distinct from an empty namespace).
• fork: works at the causal level, making a copy of the entire history.
• merge: works at the causal level

So maybe it's just delete.namespace that's the odd one out? But maybe we also decide to rename things like move.namespace into move.history or something?

It's also possible this all gets simplified if we move to a single-history-per-project model rather than the per-sub-namespace history that we have now.