Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Mental model change to versions and computed differences #150

Closed
wants to merge 1 commit into from
Closed

Mental model change to versions and computed differences #150

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions 01-basics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,21 +20,21 @@ automated version control is much better than this situation:

We've all been in this situation before: it seems ridiculous to have multiple nearly-identical versions of the same document. Some word processors let us deal with this a little better, such as Microsoft Word's "Track Changes" or Google Docs' version history.

Version control systems start with a base version of the document and then save just the changes you made at each step of the way. You can think of it as a tape: if you rewind the tape and start at the base document, then you can play back each change and end up with your latest version.
Version control systems keep track of a chain of document versions starting with a base version. This is done in an efficient manner so as to not consume large amounts of space. Given two versions, such as the current and previous or the current and the one last week, version control systems can easily compute the difference to show us what has changed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this description is not as powerful as the tape analogy. I think we want to use this intro to express the power of a VCS as a document history tracker, not a system for generating diffs.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we want to use this intro to express the power of a VCS as a document history tracker, not a system for generating diffs.

I agree on that.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1


![Changes are saved sequentially](fig/play-changes.svg)
![Sequence of versions are stored and changes can easily be computed](fig/play-changes.svg)

Once you think of changes as separate from the document itself, you can then think about "playing back" different sets of changes onto the base document and getting different versions of the document. For example, two users can make independent sets of changes based on the same document.
The idea of the differences between two documents is extremely powerful. Once we think of the differences as separate from the document itself, we can then think about "playing back" different sets of changes onto the base document and getting different versions of the document. For example, two users can make independent sets of changes based on the same document.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would also rephrase this to remove the focus on diffs. Maybe instead something like "A VCS stores every version of a document so it's always possible to retrieve a particular version. Multiple users can even modify the same document in parallel without interfering with each other."

Though I'm actually on the fence about that second sentence because I feel like that promise is only fulfilled if we talk about branching.


![Different versions can be saved](fig/versions.svg)

If there aren't conflicts, you can even try to play two sets of changes onto the same base document.

![Multiple versions can be merged](fig/merge.svg)

A version control system is a tool that keeps track of these changes for us and
helps us version and merge our files. It allows you to
decide which changes make up the next version, called a
A version control system is a tool that versions our files and helps us merge
our changes based on computing the differences between the versions.
It allows us to decide which changes make up the next version, called a
[commit](reference.html#commit), and keeps useful metadata about them. The
complete history of commits for a particular project and their metadada make up
a [repository](reference.html#repository). Repositories can be kept in sync
Expand Down