Moved Personal Experience section to chapter on history.

[gitmagic/gitmagic.git] / history.txt

== Lessons of History ==

A consequence of the distributed nature of Git is that history can be edited
easily. But if you tamper with the past, take care: only rewrite that part of
history which you alone possess. Just as nations forever argue over who
committed what atrocity, if someone else has a clone whose version of history
differs to yours, you will have trouble reconciling when your trees interact.

Of course, if you control all the other trees too, then there is no problem
since you can overwrite them.

Some developers strongly feel history should be immutable, warts and all.
Others feel trees should be made presentable before they are unleashed in
public. Git accommodates both viewpoints. Like cloning, branching and merging,
rewriting history is simply another power Git gives you, and it is up to you
to decide how to use it.

=== I Stand Corrected ===

Did you just commit, but wish you had typed a different message? Then run:

 $ git commit --amend

to change the last message. Realized you forgot to add a file? Run *git add* to
add it, and then run the above command.

Want to include a few more edits in that last commit? Then make those edits and run:

 $ git commit --amend -a

=== ... And Then Some ===

Let's suppose the previous problem is ten times worse. After a lengthy session you've made a bunch of commits. But you're not quite happy with the way they're organized, and some of those commit messages could use rewording. Then type:

 $ git rebase -i HEAD~10

and the last 10 commits will appear in your favourite $EDITOR. A sample excerpt:

    pick 5c6eb73 Added repo.or.cz link
    pick a311a64 Reordered analogies in "Work How You Want"
    pick 100834f Added push target to Makefile

Then:

- Remove commits by deleting lines.
- Reorder commits by reordering lines.
- Replace "pick" with "edit" to mark a commit for amending.
- Replace "pick" with "squash" to merge a commit with the previous one.

If you marked a commit for editing, then run:

 $ git commit --amend

Otherwise, run:

 $ git rebase --continue

So commit early and commit often: you can easily tidy up later with rebase.

=== Local Changes Last ===

You're working on an active project. You make some local commits over time, and
then you sync with the official tree with a merge. This cycle repeats itself a few times before you're ready to push to the central tree.

But now the history in your local Git clone is a messy jumble of your changes and the official changes. You'd prefer to see all your changes in one contiguous section, and after all the official changes.

This is a job for *git rebase* as described above. In many cases you can use
the *\--onto* flag and avoid interaction.

Also see *git help rebase* for detailed examples of this amazing command. You can split commits. You can even rearrange branches of a tree.

=== Rewriting History ===

Occasionally, you need the source control equivalent of airbrushing people out
of official photos, erasing them from history in a Stalinesque fashion. For
example, suppose we intend to release a project, but it involves a file that
should be kept private for some reason. Perhaps I left my credit card number in
a text file and accidentally added it to the project. Deleting the file is
insufficient, for the file can be accessed from older commits. We must remove
the file from all commits:

 $ git filter-branch --tree-filter 'rm top/secret/file' HEAD

See *git help filter-branch*, which discusses this example and gives a faster
method. In general, *filter-branch* lets you alter large sections of history
with a single command.

Afterwards, you must replace clones of your project with your revised version if you wish to interact with them later.

=== Making History ===

Want to migrate a project to Git? If it's managed with one of the more well-known systems, then chances are someone has already written a script to export the whole history to Git.

Otherwise, look up *git fast-import*, which reads text input in a specific
format to create Git history from scratch. Typically a script using this
command is hastily cobbled together and run once, migrating the project in a
single shot.

As an example, paste the following listing into temporary file, such as `/tmp/history`:
----------------------------------
commit refs/heads/master
committer Alice <alice@example.com> Thu, 01 Jan 1970 00:00:00 +0000
data <<EOT
Initial commit.
EOT

M 100644 inline hello.c
data <<EOT
#include <stdio.h>

int main() {
  printf("Hello, world!\n");
  return 0;
}
EOT


commit refs/heads/master
committer Bob <bob@example.com> Tue, 14 Mar 2000 01:59:26 -0800
data <<EOT
Replace printf() with write().
EOT

M 100644 inline hello.c
data <<EOT
#include <unistd.h>

int main() {
  write(1, "Hello, world!\n", 14);
  return 0;
}
EOT

----------------------------------

Then create a Git repository from this temporary file by typing:

 $ mkdir project; cd project; git init
 $ git fast-import < /tmp/history

You can checkout the latest version of the project with:

 $ git checkout master .

=== Personal Experience ===

In a centralized version control system, history modification is a difficult
operation, and only available to administrators. Cloning, branching, and
merging are impossible without network communication. So are basic operations
such as browsing history, or committing a change. In some systems, users
require network connectivity just to view their own changes or open a file for
editing.

Centralized systems preclude working offline, and need more expensive network
infrastructure, especially as the number of developers grows. Most
importantly, all operations are slower to some degree, usually to the point
where users shun advanced commands unless absolutely necessary. In extreme
cases this is true of even the most basic commands. When users must run slow
commands, productivity suffers because of an interrupted work flow.

I experienced these phenomena first-hand. Git was the first version control
system I used. I quickly grew accustomed to it, taking many features for
granted. I simply assumed other systems were similar: choosing a version
control system ought to be no different from choosing a text editor or web
browser.

I was shocked when later forced to use a centralized system. My often flaky
internet connection matters little with Git, but makes development unbearable
when it needs to be as reliable as local disk. Additionally, I found myself
conditioned to avoid certain commands because of the latencies involved, which
ultimately prevented me from following my desired work flow.

When I had to run a slow command, the interruption to my train of thought
dealt a disproportionate amount of damage. While waiting for server
communcation to complete, I'd do something else to pass the time, such as
check email or write documentation. By the time I returned to the original
task, the command had finished long ago, and I would waste more time trying to
remember what I was doing. Humans are bad at context switching.

There was also an interesting tragedy-of-the-commmons effect: anticipating
network congestion, individuals would consume more bandwidth than necessary on
various operations in an attempt to reduce future delays. The combined efforts
intensified congestion, encouraging individuals to consume even more bandwidth
next time to avoid even longer delays.