[PATCH] Simplified GIT usage guide

[PATCH] Simplified GIT usage guide

[David Howells]

Add a guide to using GIT's simpler features.

Signed-off-by: David Howells <dhowells@redhat.com>
---

 Documentation/git-haters-guide.txt | 1283 ++++++++++++++++++++++++++++++++++++
 1 files changed, 1283 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/git-haters-guide.txt


diff --git a/Documentation/git-haters-guide.txt b/Documentation/git-haters-guide.txt
new file mode 100644
index 0000000..51e4dac
--- /dev/null
+++ b/Documentation/git-haters-guide.txt
@@ -0,0 +1,1283 @@
+		      ===================================
+		      THE GIT HATER'S GUIDE TO THE GALAXY
+		      ===================================
+
+By David Howells <dhowells@redhat.com>
+
+Contents:
+
+ (*) Introduction.
+
+     - Disclaimer.
+
+ (*) Overview of GIT.
+
+     - Git objects.
+     - Symbolic pointers.
+     - The GIT tree.
+     - GIT trees after merging.
+
+ (*) Downloading upstream trees.
+
+     - Local mirroring.
+     - Automatic updates.
+     - Using your local mirror.
+
+ (*) Accessing the repository.
+
+     - Viewing the history.
+     - Viewing a commit.
+     - Viewing source differences.
+
+ (*) Making changes.
+
+     - Applying patches.
+     - Applying formatted patches.
+     - Incorporating GIT trees.
+
+ (*) Amending and reverting changes.
+
+     - Amending committed changes.
+     - Discarding committed changes.
+     - Reverting committed changes.
+
+ (*) Publishing changes by GIT tree.
+
+     - Setting up.
+     - Updating your development tree.
+     - Publishing your changes.
+
+ (*) Manually merging failed fetches.
+
+ (*) Locating bugs.
+
+     - Bisection.
+     - Blame.
+
+
+============
+INTRODUCTION
+============
+
+So, you want to do some Linux kernel development?  And you hear there's this
+piece of software called 'GIT' that you probably ought to be using when dealing
+with the kernel community?  Then you find out that not only was Linux started
+by this Linus Torvalds person, but GIT was too!  Perhaps it doesn't seem fair:
+Linus has not just _one_ huge piece of software named after himself, but _two_!
+And on top of that, globe spanning hardware vendors just queue up to give him
+all the herring he can eat!!
+
+Then you look at webpages about GIT.  You look at the manpages!  You run the
+commands with --help!  And you *still* don't know how to do anything complex
+with it!!  You feel certain that there's some secret rite you have to perform
+to become a GIT initiate - probably something involving two goats, an altar and
+a full moon - oh, and lots of beer (we *are* talking about kernel developers
+after all).
+
+Then you ask around, and people look at you blankly, hedge or say that it's
+easy and obvious (they should know - they wrote the damned thing).  You realise
+that the manpages are more an aide-memoire and that what you really want is
+some sort of crib sheet; something that can hold your hand whilst you cut and
+paste things from of it until you can see the point.
+
+Well, let's see if I can help...
+
+
+DISCLAIMER
+----------
+
+I don't really know what I'm doing with GIT either.  I'm not sure anyone really
+does, apart from Linus (and then only after some strange Finnish snack
+involving red and white mushrooms).  If you'd pause to wonder why things are
+like they are, you'd realise that only someone totally barking would try to
+write a kernel in the first place... and then it'd dawn on you what the mental
+state must be like of someone who'd try writing something like a source code
+management system from scratch...  and then you'd consider what it must take to
+be someone who'd do *both*.
+
+
+===============
+OVERVIEW OF GIT
+===============
+
+GIT is a source code management system.  You give it your sources to retain,
+and it manages the history of all the changes and provides you with a set of
+tools by which that history can be viewed, extracted and extended.
+
+GIT is unusual in its design in that the objects it retains are referred to by
+hashes of their content.  Because it is mathematically possible for object IDs
+to collide, large hash IDs are used to reduce the probability of a collision.
+If the content of an object changes, rather than updating the existing object,
+GIT will create a new object with a new hash ID.  Objects are _invariant_.
+
+The GIT database in a GIT tree has two sets of data:
+
+ (1) A set of objects, indexed by the object hash ID.
+
+ (2) A set of symbolic object tree heads, as object hash IDs.
+
+
+GIT OBJECTS
+-----------
+
+There are three basic types of object:
+
+ (1) File objects.
+
+     A file object contains the contents of a source file and the attributes of
+     that file (such as file mode).
+
+ (2) Directory objects.
+
+     A directory object contains the attributes of that directory plus a list
+     of file and directory objects that are members of this directory.  The
+     list includes the names of the entries within that directory and the
+     object ID of each object.
+
+ (3) Commit objects.
+
+     A commit object contains the attribute of that commit (the author and the
+     date for instance), a textual description of the change imposed by that
+     commit as provided by the committer, a list of object IDs for the commits
+     on which this commit is based, and the object ID of the root directory
+     object representing the result of this commit.
+
+     Note that a commit does not literally describe the changes that have been
+     made in the way that, say, a diff file does; it merely carries the current
+     state of the sources after that change, and points to the commits that
+     describe the state of the sources before that change.  GIT's tools then
+     infer the changes when asked.
+
+     A commit object will typically refer to one base commit when someone has
+     merely committed some changes on top of the current state, and two base
+     commits when a couple of trees have been merged.
+
+Because objects are invariant, and because they can thus be referred to by a
+hash of their contents, objects can be shared between trees simply by using the
+same object ID in two different places.  This allows objects to be compared to
+see whether they are the same thing or not simply by comparing the object ID.
+
+
+SYMBOLIC POINTERS
+-----------------
+
+GIT retains its historical information in a set of overlapping, shared trees,
+but the notion of where a tree starts isn't really a primary concept with GIT.
+What it has instead is a number of symbolic pointers to commits within the tree
+that are considered to be of some sort of significance.  These are called
+'heads' and include:
+
+ (1) The base for the current working state of the checked out sources (HEAD).
+
+ (2) Branches (by branch name).
+
+ (3) Tags (by tag name).
+
+ (4) Merge base (for incomplete merges).
+
+ (5) Points of interest, such as those that pertain to a git fetch (FETCH_HEAD
+     and ORIG_HEAD).
+
+ (6) Bisection points (when bisection is being used to find a bug).
+
+In essence, these symbolic pointers are just names or conventions for
+particular roots in the tree.  They are a name that maps to the object ID of a
+commit object.
+
+Some of them have special meanings, such as branches, that can be configured to
+behave in various ways under certain conditions (such as when a git fetch is
+performed).
+
+
+THE GIT TREE
+------------
+
+The GIT tree in its simplest terms is a backbone of commits that point to
+directories that point to files.  To give a simple example of the commit
+process, consider the sources for a project that contains one directory, D,
+which contains three files, F1, F2 and F3.
+
+This could then be committed into GIT to begin a project, in this case as
+commit C0.  This would hold version D0 of the directory, and versions F1A, F2A
+and F3A of the three files, and the GIT repository HEAD pointer would point to
+C0:
+
+	                                        +-----+
+	                                    +-->| F3A |
+	                                    |   +-----+
+	                                    |
+	        +-----+        +-----+      |   +-----+
+	HEAD--->| C0  |------->| D0  |------+-->| F2A |
+	        +-----+        +-----+      |   +-----+
+	                                    |
+	                                    |   +-----+
+	                                    +-->| F1A |
+	                                        +-----+
+
+Now imagine that someone changes file F2 and commits the change.  F1A and F3A
+are still useful, and can be shared by the new view of the world, but F2 is now
+on a new version, F2B.  The old directory object, D0, pointed to F2A, so that
+cannot be reused, and so D1 is generated.  The commit process then writes a new
+commit object, C1, that points to D1 as the state of the tree after this
+commit, and points to C0 as the commit on which C1 was based.  Finally, HEAD is
+changed to point to C1.
+
+	                                        +-----+
+	                                  +---->| F2B |
+	        +-----+        +-----+    |     +-----+
+	HEAD--->| C1  |------->| D1  |----+
+	        +-----+        +-----+    |
+	           |                      |
+	           |                      |     +-----+
+	           |                      +---->| F3A |
+	           |                      | +-->+-----+
+	           V                      | |
+	        +-----+        +-----+    | |   +-----+
+	        | C0  |------->| D0  |------+-->| F2A |
+	        +-----+        +-----+    | |   +-----+
+	                                  | |
+	                                  +-|-->+-----+
+	                                    +-->| F1A |
+	                                        +-----+
+
+Then imagine that someone changes file F1 and commits the change.  F3A is still
+viable in its original state, and F2B is usable from commit C1, but F1A is now
+obsolete and gets replaced by version F1B.  This means that neither D0 nor D1
+are usable, so directory object D2 has to be created, and new commit C2 is
+created to point to that and base commit C1.  Then HEAD is set to point to C2:
+
+	                                        +-----+
+	                                +------>| F1B |
+	        +-----+        +-----+  |       +-----+
+	HEAD--->| C2  |------->| D2  |--+
+	        +-----+        +-----+  |
+	           |                    |
+	           |                    +------>+-----+
+	           V                    | +---->| F2B |
+	        +-----+        +-----+  | |     +-----+
+	        | C1  |------->| D1  |----+
+	        +-----+        +-----+  | |
+	           |                    | |
+	           |                    +-|---->+-----+
+	           |                      +---->| F3A |
+	           |                      | +-->+-----+
+	           V                      | |
+	        +-----+        +-----+    | |   +-----+
+	        | C0  |------->| D0  |------+-->| F2A |
+	        +-----+        +-----+    | |   +-----+
+	                                  | |
+	                                  +-|-->+-----+
+	                                    +-->| F1A |
+	                                        +-----+
+
+Now, consider what would have happened if, instead of changing F1A to be F1B to
+produce C2, F2B had been reverted to the same state as F2A.  GIT would realise
+that it already has a file object to represent F2A (by comparing object IDs)
+and would use that rather than creating a new one.  The new set of files in the
+directory would then be F1A, F2A and F3A - but there's already a directory
+object for that: D0.  This would also be discovered by object ID matching, and
+would be used instead.  Commit C3 would then point to base commit C1 and
+directory D0, and HEAD would be moved to point to C3:
+
+	        +-----+
+	HEAD--->| C3  |---+
+	        +-----+   |
+	           |      |
+	           |      |                     +-----+
+	           V      |               +---->| F2B |
+	        +-----+   |    +-----+    |     +-----+
+	        | C1  |------->| D1  |----+
+	        +-----+   |    +-----+    |
+	           |      |               |
+	           |      |               |     +-----+
+	           |      |               +---->| F3A |
+	           |      |               | +-->+-----+
+	           V      |               | |
+	        +-----+   +--->+-----+    | |   +-----+
+	        | C0  |------->| D0  |------+-->| F2A |
+	        +-----+        +-----+    | |   +-----+
+	                                  | |
+	                                  +-|-->+-----+
+	                                    +-->| F1A |
+	                                        +-----+
+
+
+GIT TREES AFTER MERGING
+-----------------------
+
+Now, imagine that two GIT trees are merged.  You start off with two sets of
+commits (for convenience, I'm going to leave out the directories and files, but
+you can just assume they're there):
+
+	        +-----+                         +-----+
+	HEAD--->| C3  |                 Branch->| B3  |
+	        +-----+                         +-----+
+	           |                               |
+	           V                               V
+	        +-----+                         +-----+
+	        | C2  |                         | B2  |
+	        +-----+                         +-----+
+	           |                               |
+	           V                               V
+	        +-----+                         +-----+
+	        | C1  |<------------------------| B1  |
+	        +-----+                         +-----+
+	           |
+	           V
+	        +-----+
+	        | C0  |
+	        +-----+
+
+In the above example, I've assumed that you've got your own tree with the head
+at commit C3, and that you've got a branch that you want to merge, which has
+its head at commit B3.  After merging them, you'd end up with a directed,
+cyclic tree:
+
+	        +-----+
+	HEAD--->| C4  |----------------------------+
+	        +-----+                            |
+	           |                               |
+	           V                               V
+	        +-----+                         +-----+
+	        | C3  |                 Branch->| B3  |
+	        +-----+                         +-----+
+	           |                               |
+	           V                               V
+	        +-----+                         +-----+
+	        | C2  |                         | B2  |
+	        +-----+                         +-----+
+	           |                               |
+	           V                               V
+	        +-----+                         +-----+
+	        | C1  |<------------------------| B1  |
+	        +-----+                         +-----+
+	           |
+	           V
+	        +-----+
+	        | C0  |
+	        +-----+
+
+and the C4 commit will have pointers to *both* contributing commits, C3 and B3.
+If GIT stored the differences at each commit rather than the terminal state, it
+would have to store a delta for each contributing commit.
+
+
+==========================
+DOWNLOADING UPSTREAM TREES
+==========================
+
+The first thing you'll usually want to do with GIT is to grab a copy of the
+cutting edge version of an upstream project and build it; perhaps you want to
+work on it, perhaps because it has a fix in it that you need or perhaps because
+you like living on the cutting edge and enjoy grepping your disks to recover
+your data when things go wrong.  Whatever your reasons, you need to be able
+make a local copy of an upstream GIT tree.
+
+With GIT-based projects, grabbing a local copy of an upstream repository is
+very easy:
+
+	git clone %UPSTREAM_REPO %MY_DIR
+
+This will create a checked-out copy of the the upstream repository
+(%UPSTREAM_REPO) by pulling over the internet and sticking it in a directory on
+the local machine.
+
+For example, to fetch Linus's cutting edge kernel tree, you'd do:
+
+	git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git \
+		linux-2.6-local
+
+Then you look in linux-2.6-local and there is what you're looking for.
+
+
+LOCAL MIRRORING
+---------------
+
+You might find that you wish to run several concurrent, separate developments
+all based upon a single upstream repository.  You could simply clone each one
+as mentioned above, but that has the potential to use excessive amounts of disk
+space as each clone would include an independent copy of the entire source
+repository.
+
+What you might want to do is to set up a mirror of the upstream repository, and
+then share that mirror with each of the clones.  Even better, you can share it
+with other people who can also access the filesystem it is stored upon.
+
+So what you can do is create a local mirror:
+
+	git clone -n %UPSTREAM_REPO %MIRROR_DIR
+
+For example:
+
+	git clone -n git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git \
+		/warthog/git/linux-2.6.git
+
+The -n flag tells git to save space by not bothering to check the files out of
+the repository.  You don't really need the checkout if all you're going is to
+use this as a reference, but you can still check out if you like by omitting
+the -n.
+
+
+AUTOMATIC UPDATES
+-----------------
+
+Furthermore, you might want to automatically update your sources at some
+unfeasible hour of the morning when only Australians are awake because, say,
+your internet supply is rated more cheaply then - but you don't necessarily
+want the automatic update to dump into the sources you're actively meddling
+with.  A local mirror can help with this too.
+
+One way of automatically updating your mirror is to use cron.  To do this
+create a script that looks something like:
+
+	#!/bin/sh
+	cd %MIRROR_DIR || exit $?
+	exec git pull >/tmp/git-pull.log
+
+and chmod u+x it.  Then run the crontab program to modify your personal cron
+schedule and add something like the following line to it (not forgetting to
+remove the leading tab!):
+
+	0 %HOUR * * *       %MIRROR_SCRIPT
+
+where %HOUR is the hour you want it to go off every day.  For my local mirror
+of Linus's upstream kernel, I use:
+
+	#!/bin/sh
+	cd /warthog/git/linux-2.6 || exit $?
+	exec git pull >/tmp/git-pull.log
+
+and:
+
+	0 6 * * *       /home/dhowells/bin/do-git-pull.sh
+
+which will do the update every day at 6am.
+
+
+USING YOUR LOCAL MIRROR
+-----------------------
+
+You can then create a directory to actually do your development in by:
+
+	git clone -l -s %MIRROR_DIR %MY_DIR
+
+The "-l" tells git clone that the source (mirror) repository is on the local
+machine, that it shouldn't go over the internet for it, and that it should
+hardlink GIT objects from the source repository rather than copying them where
+possible.
+
+The "-s" says that git clone should insert a reference under %MY_DIR that
+points to the %MIRROR_DIR's collection of objects.  This means that GIT won't
+bother to copy the objects that it can get from %MIRROR_DIR at all, it'll just
+use them out of %MIRROR_DIR.
+
+    [!] NOTE: This makes %MY_DIR dependent on %MIRROR_DIR: if you delete
+    	%MIRROR_DIR or prune it you may make %MY_DIR unusable!
+
+You can repeat this again and again from the same mirror.  You can even share a
+mirror with other people that can access the filesystem holding the mirror.
+You don't need write access to it, only read.
+
+
+========================
+ACCESSING THE REPOSITORY
+========================
+
+One of the things you'll want to be able to do with what you've downloaded is
+look at changes other people have made.  GIT has some powerful tools to allow
+you to do this.
+
+
+VIEWING THE HISTORY
+-------------------
+
+You might wish, for example, to look back through the commit tree and see what
+changes have been made.  The command to do this is:
+
+	git log
+
+This will take you back through the commit information, starting at the current
+HEAD and going all the way back to the beginning if you let it:
+
+	warthog>git log
+	commit 8b1fae4e4200388b64dd88065639413cb3f1051c
+	Author: Linus Torvalds <torvalds@linux-foundation.org>
+	Date:   Wed Dec 10 15:11:51 2008 -0800
+
+	    Linux 2.6.28-rc8
+
+	commit f9fc05e7620b3ffc93eeeda6d02fc70436676152
+	Merge: b88ed20... 9a2bd24...
+	Author: Linus Torvalds <torvalds@linux-foundation.org>
+	Date:   Wed Dec 10 14:41:06 2008 -0800
+
+	    Merge branch 'sched-fixes-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/linux-2.6-tip
+
+	    * 'sched-fixes-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/linux-2.6-tip:
+	      sched: CPU remove deadlock fix
+
+	commit b88ed20594db2c685555b68c52b693b75738b2f5
+	Author: Hugh Dickins <hugh@veritas.com>
+	Date:   Wed Dec 10 20:48:52 2008 +0000
+	...
+
+
+VIEWING A COMMIT
+----------------
+
+Now that you can see the commit IDs in the history, you can examine one more
+closely:
+
+	git show
+
+to see the current HEAD commit, or:
+
+	git show %COMMIT_ID
+
+to see a particular commit:
+
+	warthog>git show 1da177e
+	commit 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2
+	Author: Linus Torvalds <torvalds@ppc970.osdl.org>
+	Date:   Sat Apr 16 15:20:36 2005 -0700
+
+	    Linux-2.6.12-rc2
+
+	    Initial git repository build. I'm not bothering with the full history,
+	...
+	diff --git a/COPYING b/COPYING
+	new file mode 100644
+	index 0000000..2a7e338
+	--- /dev/null
+	+++ b/COPYING
+	@@ -0,0 +1,356 @@
+	+
+	+   NOTE! This copyright does *not* cover user programs that use kernel
+	...
+
+
+VIEWING SOURCE DIFFERENCES
+--------------------------
+
+The 'git-show' command shows you what it thinks the differences are that you
+want to see, between a commit and its first listed base commit.  However, there
+are other differences you might wish to see.
+
+Firstly, you might like to see the differences between what's in the current
+HEAD commit, and what you've got checked out:
+
+	git diff
+
+or you might wish to see the differences between two particular commits, for
+example:
+
+	git diff v2.6.24 v2.6.25
+
+
+==============
+MAKING CHANGES
+==============
+
+So you've got a fresh development GIT tree and you want to make changes in it
+and commit them to it.  The first is easy enough: just use your preferred text
+editor to edit the files directly, or you could use sed or perl to apply some
+textual transformations - that's entirely up to you.
+
+However, once you've made those changes and you've compiled and tested them,
+you'll probably want to consign them to GIT.
+
+Files you've added must be marked by:
+
+	git add <filename>
+
+and files you've deleted must be noted by:
+
+	git rm <filename>
+
+so that GIT knows to include or exclude these files from its tree.
+Furthermore, you must tell GIT about any files that have changed that you want
+to be updated also:
+
+	git add <filename>
+
+You can then commit your changes.  This is done by running:
+
+	git commit
+
+Rather than doing lots of git add and git rm commands to register updated and
+removed files, you can give git commit a '-a' flag.  Note, though, that this
+takes no account of new files that git doesn't already know about.  Those must
+be added manually.
+
+git commit will pop up your favourite editor, asking you to enter a commit
+message describing your changes (don't forget to add your sign-off).  It will
+list the files it sees that have been added, altered and removed, and will
+differentiate between those that it has been told about (and thus will include)
+and those it hasn't (which will be ignored).
+
+After git commit completes successfully, 'git show' should show the new commit
+you've just made, and gitk should show the new tree structure with your new
+commit at the top.
+
+
+APPLYING PATCHES
+----------------
+
+If you have a patch file you wish to apply, you can do that with:
+
+	git apply <patch-file>
+
+This will make the changes specified by the patch, but it won't register any of
+the changes and won't record any of the metadata that might be in the patch
+file, such as authorship, description or attribution.  That has to be done
+manually as if you'd made the changes yourself.
+
+
+APPLYING FORMATTED PATCHES
+--------------------------
+
+Sometimes you may wish to incorporate a patch that someone has emailed you.
+You could use the 'patch' or 'git apply' programs and then set up the commit
+information manually, but if someone has sent you an appropriately formatted
+message - perhaps in an email - you can have GIT import the metadata from the
+message rather than you having to type it manually.
+
+If someone has given you an email or appropriately formatted patch file, the
+following command can import it:
+
+	git am <patch-file>
+
+If successful, this will automatically register all added, altered and removed
+files and commit the changes for you.  The commit message will be concocted
+from the description and email headers (From: and Subject: for instance).  If
+you want to add your own sign-off to the bottom of the commit message whilst
+you're at it, you can add a '-s' flag:
+
+	git am -s <patch-file>
+
+You may find it convenient to edit unformatted patches to make it possible to
+use 'git am' rather than 'git apply'.
+
+
+INCORPORATING GIT TREES
+-----------------------
+
+And sometimes, rather then sending you patches, people may attempt to
+contribute changes to you that are contained within GIT trees and you may wish
+to incorporate these into your development tree.
+
+To do this, the following command will work:
+
+	git pull %CONTRIB_REPO %CONTRIB_BRANCH
+
+where %CONTRIB_REPO is the URL of a repository and %CONTRIB_BRANCH is the name
+of the branch within that repository (usually this will be 'master').
+
+If successful, this will either just stack the pulled changes directly on top
+of your tree (assuming the contributed tree is based on the head of your tree)
+or it will automatically produce a merge commit indicating that the resulting
+tree is a union of the changes in your tree and the contributed tree.
+
+If unsuccessful due to conflicting changes, you'll need to perform the merge
+manually and perform the commit yourself.  See the "Manually merging failed
+fetches" section.
+
+An example of the command line you might use is:
+
+	git pull git://git.infradead.org/mtd-2.6.git master
+
+which will pull master branch of the upstream MTD tree into the GIT tree you're
+currently in.
+
+
+==============================
+AMENDING AND REVERTING CHANGES
+==============================
+
+There will be times when you make a mistake in your changes, and you find that
+you either want to amend them, or you want to discard them entirely.  GIT
+provides a number of tools to do this.
+
+If you make a mistake in changes you haven't yet committed, you can just edit
+them again with your text editor, or if you'd prefer to discard all the changes
+you made to a particular file, you can do:
+
+	git checkout <filename>
+
+This will just wipe away the changes that you've made and restore the file to
+the state it has recorded for it as part of the topmost commit.
+
+
+AMENDING COMMITTED CHANGES
+--------------------------
+
+If you've committed some changes and you realise that those changes are
+incorrect, you can amend them without precisely making a whole new commit -
+provided you haven't committed anything else on top of them.
+
+To do this, you make your changes, run git add and git rm as normal, and then
+do:
+
+	git commit --amend
+
+This will replace the topmost commit with a similar commit that includes the
+amendments.  The old commit will be displaced from the tree and will not appear
+again.
+
+Changes that are buried beneath further commits unfortunately have to be
+altered by making a new commit with the amendments, unless you wish to discard
+all the commits down to the one that needs amending, and then apply them all
+again.
+
+
+DISCARDING COMMITTED CHANGES
+----------------------------
+
+Upon occasion, you'll want to discard one or more commits entirely from the top
+of your tree.  To do this you need to find the ID of the latest commit that you
+want to keep.  Everything from the commit after that to the current commit will
+be discarded.
+
+You can find the commit ID in a number of ways.  Firstly, you can use 'git log'
+to look back through the commits.  The commit ID is shown as something like:
+
+	commit 6c34bc2976b30dc8b56392c020e25bae1f363cab
+
+Secondly, you can use gitk: select the commit of interest; the commit ID
+appears in the box labelled "SHA1 ID".
+
+You can then perform the discard with the following command:
+
+	git reset --hard %COMMIT_ID
+
+Using the above commit ID as an example, you could do:
+
+	git reset --hard 6c34bc2976b30dc8b56392c020e25bae1f363cab
+
+
+REVERTING COMMITTED CHANGES
+---------------------------
+
+And sometimes you'll want to revert changes that you've committed, but that are
+now buried beneath other commits.  Short of discarding and reapplying commits,
+you have to apply a reverse patch:
+
+	git diff %COMMIT_ID | patch -p1 -R
+
+and then commit it.  Both the original application and the reversion will be
+retained by GIT.
+
+
+==============================
+PUBLISHING CHANGES BY GIT TREE
+==============================
+
+Now that you've got a tree and have mangled it in unspeakable ways, you
+probably want to donate the glory of your works back to the community - usually
+with an eye to getting your changes pulled into an upstream maintainer's
+repository.  Your upstream maintainer may then push your changes on to their
+upstream maintainer, until it ends into the ultimate upstream repository
+(Linus's linux-2.6 tree in the case of the Linux kernel).
+
+You could, of course, just push patches to the upstream maintainer, be that
+Linus or one of his cronies in the case of the Linux kernel, or some other
+person if some other project.
+
+GIT, however, leans strongly towards another option.  If you can get access to
+a computer that is accessible by way of the internet, you might be able to set
+up a public GIT tree upon it and ask an appropriate upstream maintainer to pull
+from that.
+
+That computer, however, may not be particularly convenient for developing on:
+it may be remote from where you're working, for example, perhaps even on a
+different continent - so you'll probably want to have two trees: a remote,
+public, published tree, and a local private tree where you can break stuff at
+will.  I'm going to assume the two trees approach.
+
+
+SETTING UP
+----------
+
+First of all, you'll need to set up your two trees.  There are a number of
+steps to go through to do this:
+
+ (1) Find somewhere that's accessible by the internet (%REMOTE_BOX) that you
+     have SSH access to, and set up a public GIT tree that's a clone of the
+     upstream tree you want to use as a base:
+
+	ssh %REMOTE_BOX
+	cd /my/git/trees
+	git clone -n --bare %UPSTREAM_REPO %MY_DIR
+
+     Where %UPSTREAM_REPO is something like:
+
+	git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
+
+     This will create a directory called /my/git/trees/%MY_DIR that contains a
+     bare GIT repository to which you can upload your changes.  There will be
+     no checked out files here, and everything that would usually be in the
+     .git directory is in the top directory instead.
+
+     If your tree is on the same box as the tree you want to fork, you can
+     tell GIT to use that rather than going to the internet:
+
+	git clone -l -s -n --bare %UPSTREAM_DIR %MY_DIR
+
+     For example, I might wish to set up a tree to publish NOMMU changes so
+     that they're available through git.kernel.org.  To that end, I would do:
+
+	ssh master.kernel.org
+	cd /pub/scm/linux/kernel/git/dhowells
+	git clone -l -n -s --bare \
+		/pub/scm/linux/kernel/git/torvalds/linux-2.6.git linux-2.6-nommu
+
+
+ (2) You should set the description on your public repository:
+
+	echo %DESCRIPTION >%MY_DIR/description
+
+     For example:
+
+	echo "NOMMU development" >linux-2.6-nommu/description
+
+     This will be published through the GIT web interface if one is set up, and
+     so can be viewed by going to the appropriate URL.  For instance:
+
+	http://git.kernel.org/?p=linux/kernel/git/dhowells/linux-2.6-nommu.git
+
+
+ (3) Now go to the work machine on which you'll be doing your development.
+     You'll need to create a local fork of your public GIT repository.  You can
+     do this by:
+
+	git clone ssh://%REMOTE_BOX/my/git/trees/%MY_DIR %DEVEL_DIR
+
+     This will create a checked-out GIT tree in a directory (%DEVEL_DIR) that
+     you can later use for development.  If you have a local mirror of the
+     upstream tree that you're using as a base, you can tell git to use the
+     objects from that to save space:
+
+	git clone --reference %LOCAL_UPSTREAM_MIRROR \
+		ssh://%REMOTE_BOX/my/git/trees/%MY_DIR \
+		%DEVEL_DIR
+
+     [!] NOTE: You must use ssh: and not git: to clone your tree because you
+     	       need to be able to push back (write) to your public tree.
+
+     To continue my example, I have a local mirror of Linus's kernel, regularly
+     updated by cron, and so to make my local NOMMU development tree, I would
+     do:
+
+	git clone --reference /warthog/git/linux-2.6 \
+		ssh://master.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-2.6-nommu.git \
+		linux-2.6-nommu
+
+
+ (4) Now you need to set up your local GIT tree to make it possible (a) update
+     your development tree by pulling in the upstream tree, and (b) publish
+     your changes by pushing them to your public tree.
+
+	cd %DEVEL_DIR
+
+     Tell your repository where to find the upstream tree:
+
+	git remote add %UPSTREAM %UPSTREAM_REPO
+
+     where %UPSTREAM is the name you by which you want to refer to the upstream
+     repository to git pull.  For Linus's upstream kernel, you might wish to
+     use 'linus' for example.
+
+     In my example, I did the following to pull Linus's tree into branches of
+     my tree:
+
+	cd linux-2.6-nommu
+	git remote add linus \
+		git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
+
+     Looking in .git/config, I now see section that looks like this:
+
+	[remote "origin"]
+		url = ssh://master.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-2.6-nommu.git
+		fetch = +refs/heads/*:refs/remotes/origin/*
+	[branch "master"]
+		remote = origin
+		merge = refs/heads/master
+	[remote "linus"]
+		url = git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
+		fetch = +refs/heads/*:refs/remotes/linus/*
+
+
+ (5) You should now be able to update your development tree from the upstream
+     repository to make sure that works:
+
+	git fetch -v %UPSTREAM
+
+     In my case, that's:
+
+	git fetch -v linus
+
+     If you've just created the repository, it'll probably just say that things
+     are up to date:
+
+	From git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6
+	 = [up to date]      master     -> linus/master
+
+     [!] NOTE: I cannot determine a way of making "git pull linus" work without
+     	 setting branch.master.remote to 'linus'.
+
+
+ (6) And then you should be able to publish your development tree by pushing it
+     to your public tree, thus allowing the rest of the world to see your
+     changes.
+
+	git push -v origin
+
+
+ (7) Finally you should be able to pull your published tree back into your
+     development tree, and it should just say that it's up to date:
+
+	git pull -v
+
+
+UPDATING YOUR DEVELOPMENT TREE
+------------------------------
+
+Okay: so you've got your tree, and you've made changes to it, and now Linus has
+gone and dumped five thousand patches into his tree, making the base for your
+changes obsolete.  You need to update your tree and fix up your changes.
+
+If you haven't yet committed your changes, you'll have to siphon them off into
+a file:
+
+	git diff >a.diff
+
+and deapply them:
+
+	patch -p1 -R <a.diff
+
+You can then update your tree from the upstream tree with no fear of a conflict
+(assuming you don't also have changes that you have committed).  Once you've
+updated your tree, you can reapply your changes:
+
+	patch -p1 <a.diff
+
+And then fix up the rejects with your favourite editor and a few choice curses.
+
+
+To actually update your tree, you can do the following:
+
+	git fetch %UPSTREAM
+
+In my example, that'd be:
+
+	git fetch linus
+
+If you have committed changes, this will attempt to merge them, but you may
+still need to fix them up.  If everything went smoothly this will automatically
+commit a merge on top of the tree and set the HEAD pointer to that.  This merge
+will point at your last tree and the tree you just merged from upstream, and
+will indicate that the resulting tree is a combination of both.  Of course, you
+shouldn't assume it will still compile, let alone still work...
+
+If you do need to fix them up, refer to the "Manually merging failed fetches"
+section for guidance.
+
+You can view the merge that git pull committed by:
+
+	git show
+
+And you can view the tree structure at that point with the gitk command.
+
+
+PUBLISHING YOUR CHANGES
+-----------------------
+
+Finally, you're in a position to make your changes available.  Firstly, you
+have to commit them to your development tree (as mentioned previously) and then
+you have to make them available to the rest of the world.  To do that, simply
+run:
+
+	git push
+
+which will apply the changes to your public tree.  If you have web access to
+your git tree, these will eventually become visible through there.
+
+You may then have to tell your upstream maintainer what you'd like them to pull
+from your tree.  The standard way to do this is to do:
+
+	git request-pull %BASE_ID %MY_REPO >/tmp/request.txt
+
+where %BASE_ID is the head of the tree on which your changes are based, and
+%MY_REPO is the public URL of your repository.  If you have your development
+git tree configured to know where the upstream remote repository is, then if
+you've ever done 'git fetch' you should have a branch for it, named something
+like "%UPSTREAM/%UPSTREAM_BRANCH" where %UPSTREAM is the name you gave to 'git
+remote' and %UPSTREAM_BRANCH is the upstream branch on which you've based your
+development (almost certainly 'master').
+
+This command will generate a list of all the patches between %BASE_ID and the
+head of your tree that you are asking to be pulled.
+
+In my example, I can do:
+
+	git request-pull linus/master \
+		git://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-2.6-nommu.git \
+		>/tmp/request.txt
+
+You should then edit /tmp/request.txt to include a description of what you're
+trying to achieve with these patches, and then mail the whole file to the
+upstream maintainer.
+
+[!] NOTE: It may take some time for the git push to take full effect.  Before
+    that time is up, git request-pull may give spurious warnings and the test
+    it produces may say that the branch is unverified.
+
+
+===============================
+MANUALLY MERGING FAILED FETCHES
+===============================
+
+Occasionally, when you pull someone else's tree in to your repository, either
+because the base needs updating or because you're incorporating stuff from a
+contributor, the merge will fail due to conflicts between the changes you have
+made in your tree, and the changes you're importing.
+
+GIT will try and automatically merge where possible, but it can't always manage
+it.  In such cases you have to unlimber your text editor and fix it manually.
+
+GIT will report the files that need merging during the git fetch/git pull:
+
+	CONFLICT (content): Merge conflict in drivers/char/tty_audit.c
+
+and they can also be determined by looking in ".git/MERGE_MSG".
+
+GIT will interpolate markers into the affected files, along with both versions
+of the code:
+
+	<<<<<<< HEAD:drivers/char/tty_audit.c
+					 tsk->pid, uid, loginuid, sessionid,
+	=======
+					 tsk->pid, tsk->uid, loginuid, sessionid,
+	>>>>>>> b3985e2bf6ce51ae943208af4bd336287fb34ed6:drivers/char/tty_audit.c
+
+The first section (<<<<<<<< to =======) is the version from your tree, the
+second section (======= to >>>>>>>) is the version from the tree being
+imported.  The markers must be removed, and the conflicting code resolved down
+to the appropriate final version.
+
+
+Once that is done, git add (or git rm) must be called on the changed files so
+that git commit knows to include them in the new head.  It works exactly like
+changing files normally (as per the "Making changes" section), except that GIT
+has stored extra data that will go into the merge commit when git commit
+creates it.
+
+
+=============
+LOCATING BUGS
+=============
+
+There will be times when the program you've built malfunctions.  It happens now
+and then even to the best of projects.  Sometimes you can easily locate the bug
+by looking at the symptoms and the debugging output and then eyeballing the
+code, and sometimes you can't.
+
+For very big projects such as the Linux kernel, finding a bug that someone else
+has inadvertently introduced can be very hard, but GIT allows you to take
+advantage of the fact that the changes are introduced a bit at a time with
+clear boundaries (commits) to make life a bit easier.
+
+
+BISECTION
+---------
+
+What you really want to be able to do is to isolate the commit that's causing
+the malfunction, but with automation support so that you don't have to trace
+the commit tree yourself.  GIT has a tool to do this: git bisect.
+
+The way this works is to take two points in the tree: one at which you know the
+program malfunctions, and one at which you know it doesn't, and then chop its
+way through the tree to locate the failing commit.
+
+To illustrate this:
+
+ (1) Assume that you're dealing with the kernel, and that you find that after
+     Linus's merge window, 2.6.25-rc1 does not boot for you, but you know that
+     2.6.24 did prior to the window.
+
+     Firstly you have to start your search and describe the bounds (the working
+     and non-working points).  This is done with the following commands:
+
+	git bisect start [%BAD_COMMIT [%GOOD_COMMIT]]
+	git bisect bad [%BAD_COMMIT]
+	git bisect good [%GOOD_COMMIT]
+
+     where %BAD_COMMIT and %GOOD_COMMIT are optional commit object IDs or
+     symbolic representations thereof.  The 'bad' command is unnecessary if
+     %BAD_COMMIT is given to 'start', and the 'good' command is not required if
+     %GOOD_COMMIT is given to 'start'.
+
+     So, in the example we're looking at, you could do:
+
+	git bisect start
+	git bisect bad v2.6.25-rc1
+	git bisect good v2.6.24
+
+     or:
+
+	git bisect start v2.6.25-rc1
+	git bisect good v2.6.24
+
+     or:
+
+	git bisect start v2.6.25-rc1 v2.6.24
+
+	[!] NOTE: This is using a symbolic tag 'v2.6.24' to refer to the last
+     	    commit before 2.6.24 was declared.
+
+
+     However, if 2.6.25-rc1 is at currently at the head of your tree, you can
+     do:
+
+	git bisect start
+	git bisect bad
+
+     to indicate that this malfunctioned, or you could do this in a single
+     command:
+
+	git bisect start HEAD
+
+     to start bisection _and_ indicate that the HEAD revision is bad.
+
+
+     Alternatively, if you're at a point where the program _does_ work, you can
+     pass either HEAD or no parameter to the 'good' bisection command, or pass
+     HEAD as the %GOOD_COMMIT parameter to the 'start' bisection command.
+
+
+ (2) Now GIT will rumble through the commits between the two points you have
+     declared, and set the current HEAD of the repository to a point that
+     approximates midway between the two:
+
+	warthog>git bisect start v2.6.25-rc1 v2.6.24
+	Bisecting: 4814 revisions left to test after this
+	[d2e626f45cc450c00f5f98a89b8b4c4ac3c9bf5f] x86: add PAGE_KERNEL_EXEC_NOCACHE
+
+     and then it will check out the sources to reflect their state at this point.
+
+
+ (3) You should now attempt to compile this and test it.  If the test succeeds,
+     you should run the command:
+
+	git bisect good
+
+     If the test fails, run the command:
+
+	git bisect bad
+
+     These will tell GIT to binary chop the commits between either the current
+     point and the good end or the current point and the bad end to find a new
+     commit to test:
+
+	warthog>git bisect bad
+	Bisecting: 2406 revisions left to test after this
+	[fb46990dba94866462e90623e183d02ec591cf8f] [NETFILTER]: nf_queue: remove unnecessary hook existance check
+	warthog>git bisect good
+	Bisecting: 1203 revisions left to test after this
+	[936722922f6d2366378de606a40c14f96915474d] [IPV4] fib_trie: compute size when needed
+
+     As for when bisection started, GIT will set the current HEAD pointer and
+     then check out the sources.  You should repeat step (3).
+
+     If the commit is broken for you and the compile fails, run the command:
+
+	git bisect skip
+
+     this will cause the bisection algorithm to move onto the next commit in
+     the hope that this one will be better:
+
+	warthog>git bisect skip
+	Bisecting: 1203 revisions left to test after this
+	[1328042e268c936189f15eba5bd9a5a4605a8581] [IPV4] fib_trie: use hash list
+
+     this will change the HEAD pointer and check out the sources.  Repeat step
+     (3).
+
+
+ (4) Eventually, after you've tested a number of different commits, GIT will
+     tell you that it has narrowed the problem down to either a single commit,
+     or if there were compile errors that got in the way, a range of commits:
+
+	warthog>git bisect bad
+	e3ac5298159c5286cef86f0865d4fa6a606bd391 is first bad commit
+	commit e3ac5298159c5286cef86f0865d4fa6a606bd391
+	Author: Patrick McHardy <kaber@trash.net>
+	Date:   Wed Dec 5 01:23:57 2007 -0800
+
+	    [NETFILTER]: nf_queue: make queue_handler const
+
+	    Signed-off-by: Patrick McHardy <kaber@trash.net>
+	    Signed-off-by: David S. Miller <davem@davemloft.net>
+	...
+
+
+ (5) At any time during the bisection process, you can use:
+
+	git show
+
+     to examine the commit currently selected for testing, and:
+
+	git bisect log
+
+     to view the log of information provided by you through git bisect start,
+     good and bad, and:
+
+	git bisect visualize
+
+     to start up the gitk program to show you a graphical view of the current
+     good-to-bad range of commits as narrowed down by bisection.
+
+
+ (6) You should then end the bisection process by:
+
+	git bisect reset
+
+
+BLAME
+-----
+
+Now imagine that rather than indulging in bisection you've found a bug by
+simply looking at the code: who do you tell about it?  You could look at the
+banner comment at the top of the file to look for names and email addresses,
+and you could also look in the kernel MAINTAINERS file or its equivalent, but
+the person you really want to harangue is whoever made the change...
+
+There's a very useful GIT tool to help determine this:
+
+	git blame <file>
+
+also known as:
+
+	git annotate <file>
+
+which will give you a list of lines in a source file against who changed them
+last and in what commit.  You may find that your favourite editor has a
+facility to run this for you (Emacs has vc-annotate, bound to C-x v g, for
+example).
+
+Running git blame on the kernel's README file, for example, might show:
+
+	warthog>git blame README
+	620034c8 (Jesper Juhl                    2006-12-07 00:45:58 +0100   1)         Linux kernel release 2.6.xx <http://kernel.org/>
+	^1da177e (Linus Torvalds                 2005-04-16 15:20:36 -0700   2)
+	^1da177e (Linus Torvalds                 2005-04-16 15:20:36 -0700   3) These are the release notes for Linux version 2.6.  Read them carefully,
+	...
+
+The hex number that occurs first on the line is a truncated commit object ID,
+and this can be passed to git-show (remove the '^' symbol first, if given).
+
+	warthog>git show 1da177e
+	commit 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2
+	Author: Linus Torvalds <torvalds@ppc970.osdl.org>
+	Date:   Sat Apr 16 15:20:36 2005 -0700
+	...

Re: [PATCH] Simplified GIT usage guide

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 3038 bytes --]

On Fri, Dec 12, 2008 at 06:28:27PM +0000, David Howells <dhowells@redhat.com> wrote:
> + (1) File objects.
> +
> +     A file object contains the contents of a source file and the attributes of
> +     that file (such as file mode).

This is incorrect, a 'blob' contains only the contents of the blob, the
file mode is stored in the 'tree' object.

> + (2) Directory objects.
> +
> +     A directory object contains the attributes of that directory plus a list
> +     of file and directory objects that are members of this directory.  The
> +     list includes the names of the entries within that directory and the
> +     object ID of each object.
> +
> + (3) Commit objects.
> +
> +     A commit object contains the attribute of that commit (the author and the
> +     date for instance), a textual description of the change imposed by that
> +     commit as provided by the committer, a list of object IDs for the commits
> +     on which this commit is based, and the object ID of the root directory
> +     object representing the result of this commit.
> +
> +     Note that a commit does not literally describe the changes that have been
> +     made in the way that, say, a diff file does; it merely carries the current
> +     state of the sources after that change, and points to the commits that
> +     describe the state of the sources before that change.  GIT's tools then
> +     infer the changes when asked.
> +
> +     A commit object will typically refer to one base commit when someone has
> +     merely committed some changes on top of the current state, and two base
> +     commits when a couple of trees have been merged.

Is there any reason you hide the tag object?

> +where %HOUR is the hour you want it to go off every day.  For my local mirror
> +of Linus's upstream kernel, I use:
> +
> +	#!/bin/sh
> +	cd /warthog/git/linux-2.6 || exit $?
> +	exec git pull >/tmp/git-pull.log
> +
> +and:
> +
> +	0 6 * * *       /home/dhowells/bin/do-git-pull.sh
> +
> +which will do the update every day at 6am.

Using git clone --mirror would be much efficient, I think.

> +The "-l" tells git clone that the source (mirror) repository is on the local
> +machine, that it shouldn't go over the internet for it, and that it should
> +hardlink GIT objects from the source repository rather than copying them where
> +possible.

Here and later below, IIRC -l is the default for local clones.

> +	cd /my/git/trees
> +	git clone -n --bare %UPSTREAM_REPO %MY_DIR

--bare implies -n.

> +If you haven't yet committed your changes, you'll have to siphon them off into
> +a file:
> +
> +	git diff >a.diff
> +
> +and deapply them:
> +
> +	patch -p1 -R <a.diff
> +
> +You can then update your tree from the upstream tree with no fear of a conflict
> +(assuming you don't also have changes that you have committed).  Once you've
> +updated your tree, you can reapply your changes:
> +
> +	patch -p1 <a.diff

Why not using git stash and git stash pop?

Or at least git apply and git checkout - leaving out patch(1) from the
game.

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Simplified GIT usage guide

[Johannes Schindelin]

Hi,

On Fri, 12 Dec 2008, David Howells wrote:

>  Documentation/git-haters-guide.txt | 1283 ++++++++++++++++++++++++++++++++++++

I am sure we want to have something like that in git.git.

> +I don't really know what I'm doing with GIT either.

Strike the "either".

> +===============
> +OVERVIEW OF GIT
> +===============

Your overview seems to be what "Git from the bottom up" is all about (see 
the Git Wiki for more information where to find it).

>From my experience with new users, this is exactly the wrong way to go 
about it.  You don't introduce object types of the Git database before 
telling the users what the heck they are good for.  And most users do not 
need to bother with tree objects either, anyway.  So maybe you just tell 
them what the heck the object types are good for, without even teaching 
them the object types at all.

So I think that your document might do a good job scaring people away from 
Git.  But I do not believe that your document, especially in the tone it 
is written, does a good job of helping Git newbies.

Ciao,
Dscho

P.S.: No, I haven't read the whole document.  Still, I think I am 
qualified enough to estimate what the average reader's first impression 
would be.

Re: [PATCH] Simplified GIT usage guide

[Paul E. McKenney]

On Fri, Dec 12, 2008 at 07:57:38PM +0100, Johannes Schindelin wrote:
> Hi,
> 
> On Fri, 12 Dec 2008, David Howells wrote:
> 
> >  Documentation/git-haters-guide.txt | 1283 ++++++++++++++++++++++++++++++++++++
> 
> I am sure we want to have something like that in git.git.

So am I.  Except that I am not being sarcastic.  ;-)

> > +I don't really know what I'm doing with GIT either.
> 
> Strike the "either".

Not in my case.  And I am far from alone.

Let's face it, if you really do know what you are doing with GIT, you
probably are not a GIT-hater, and thus not in the target audience for
Dave's document.

> > +===============
> > +OVERVIEW OF GIT
> > +===============
> 
> Your overview seems to be what "Git from the bottom up" is all about (see 
> the Git Wiki for more information where to find it).
> 
> From my experience with new users, this is exactly the wrong way to go 
> about it.  You don't introduce object types of the Git database before 
> telling the users what the heck they are good for.  And most users do not 
> need to bother with tree objects either, anyway.  So maybe you just tell 
> them what the heck the object types are good for, without even teaching 
> them the object types at all.
> 
> So I think that your document might do a good job scaring people away from 
> Git.  But I do not believe that your document, especially in the tone it 
> is written, does a good job of helping Git newbies.
> 
> Ciao,
> Dscho
> 
> P.S.: No, I haven't read the whole document.  Still, I think I am 
> qualified enough to estimate what the average reader's first impression 
> would be.

Not sure I agree.  You might well know too much about git to understand
what it looks like to a new user, particularly a new user with a
couple decades experience with earlier source-code control system.
(RCS, anyone?)

In particular, David's guide was quite helpful to me.  It would have been
even more helpful had it existed when I first tried (unsuccessfully)
to use GIT.  In particular, GIT's requirement that I tell it about new
versions of existing files (either with "git add" or "git commit -a")
was extremely counter-intuitive, and caused me no end of pain.

There might well be a need for different approaches for different types
of newbies.  Guys like myself who have used source-code control tools
of one type or another for a couple decades can -definitely- benefit
from Dave's approach.  In particular, Dave's broad-brush description of
GIT's internals is enough to explain why the heck I should have to tell
GIT about a new version of a file THAT IT ALREADY KNOWS ABOUT!!!
"Why should I need to add a file that is already there???"

Don't get me wrong -- as I have gained experience with GIT over the past
six months or so, I have found a number of situations where GIT's
insisting that I tell it about new versions of existing files has been
helpful, for example, when I suddenly realize that a given change should
be applied in multiple commits, with different groups of files in each
commit.  In that case, doing a series of "git add" and "git commit"
commands works very nicely.

So I am -not- suggesting changing git.  Once you get used to it, it
works out well.  I suppose that you could have a "git new-version"
command as a synonym for "git add", but I doubt that it is worth it.

But the "git add" issue turned me away from git several times in the past
three years.  And for quite some time, I used git in read-only mode,
because very strange things happened (from my viewpoint) whenever I
tried changing anything.

After using GIT reasonably heavily for the past six months, I am actually
learning to like it, and have even starting using it for my own projects.
But my experience is that git is at best an acquired taste for those of
us who grew up with traditional source-code control systems.  Such
people will benefit greatly from a git-haters guide, and git's user
population will grow as a result.

							Thanx, Paul

Re: [PATCH] Simplified GIT usage guide

[Junio C Hamano]

"Paul E. McKenney" <paulmck@linux.vnet.ibm.com> writes:

> On Fri, Dec 12, 2008 at 07:57:38PM +0100, Johannes Schindelin wrote:
> ...
>> I am sure we want to have something like that in git.git.
>
> So am I.  Except that I am not being sarcastic.  ;-)

Hmm, but we seem to already have too many intro-to-git documents in tree.
Perhaps good points in the document can be used to augment or replace
parts of existing documents?  For example, which part of the new
documentation would have helped you avoid the pain you mentioned below...

> In particular, David's guide was quite helpful to me.  It would have been
> even more helpful had it existed when I first tried (unsuccessfully)
> to use GIT.  In particular, GIT's requirement that I tell it about new
> versions of existing files (either with "git add" or "git commit -a")
> was extremely counter-intuitive, and caused me no end of pain.

... and which part of the existing user manual or tutorial should have
talked about it to help you?

> But my experience is that git is at best an acquired taste for those of
> us who grew up with traditional source-code control systems.  Such
> people will benefit greatly from a git-haters guide,...

"Acquired taste" is a much nicer and more diplomatic way to say the same
thing as what Linus often refers as "unlearning the braindamage inflicted
by years of using CVS." ;-)

> ..., and git's user
> population will grow as a result.

I do not think it constitutes any basis for judging the merit of having
the document in git.git tree.  The world domination is not our goal, but
it may come as a mere side effect of being the best in the business.

Re: [PATCH] Simplified GIT usage guide

[Paul E. McKenney]

On Thu, Dec 18, 2008 at 04:28:11PM -0800, Junio C Hamano wrote:
> "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> writes:
> 
> > On Fri, Dec 12, 2008 at 07:57:38PM +0100, Johannes Schindelin wrote:
> > ...
> >> I am sure we want to have something like that in git.git.
> >
> > So am I.  Except that I am not being sarcastic.  ;-)
> 
> Hmm, but we seem to already have too many intro-to-git documents in tree.
> Perhaps good points in the document can be used to augment or replace
> parts of existing documents?  For example, which part of the new
> documentation would have helped you avoid the pain you mentioned below...

I would be OK with it being in linux-2.6.git rather than git.git,
if that helps.  Certainly there seems to be room for a description
of how to use git within the Linux community.

> > In particular, David's guide was quite helpful to me.  It would have been
> > even more helpful had it existed when I first tried (unsuccessfully)
> > to use GIT.  In particular, GIT's requirement that I tell it about new
> > versions of existing files (either with "git add" or "git commit -a")
> > was extremely counter-intuitive, and caused me no end of pain.
> 
> ... and which part of the existing user manual or tutorial should have
> talked about it to help you?

The part that describes the differences between git and traditional
source-code-control packages.  A few examples:

o	Having to add files that are already there when changing them.
	"Why do I need to add it?  Can't git see that it is -already-
	-there-???"  ;-)

	The key point is that traditional source-code has a file as a
	first-class concept.  Not git, which instead has a particular
	revision of a file as the front-and-center first-class object.
	Simply saying this is insufficient, as both git and (say) RCS
	track both files and revisions to files.  If you do simply state
	this, the RCS guy will think he understands you, but he won't
	have a clue.

o	The fact that git's log changes depending on what branch
	you are on is quite confusing to those of us who are used
	to history being invariant.  I am learning to do "git branch -l"
	to see where I have been in my own git trees.  No doubt there
	is some way to dump out the relationship between the various
	branches and some convention for "the current revision" for
	the upstream git tree, but I have not found it yet.

	Not that I have looked all that hard.  The Linux kernel has
	a nice linear series of version tags that tell me what I need.
	But that is only because I work on stuff that is out of the
	quickly changing mainstream.  My own projects I still remember,
	and keep textfiles listing what each branch is intended for.

o	The fact that you can put a git archive into a state so that
	"git remote update" changes the archive, but doesn't change
	your view, nor any obvious-to-the-newbie attribute of the view.
	The only way I know to get out of this is to carefully record
	the new SHA hash that "git remote update" prints, and then do a
	"git checkout" on that SHA hash.  Given a quiescent archive,
	how do I find the points of interest?  For -tip, I can usually
	check out "tip/core/rcu" and get where I need to go, but I am
	quite unclear on navigation through a git archive.  For one
	thing, git will sometimes interpret "tip/core/rcu" as a path
	name rather than as a navigation point (or whatever the heck
	it really is).

o	I need to work with multiple views of the same git archive.
	Doing "git checkout"s back and forth within a single archive
	does not do what I need.  I have been experimenting with various
	"git clone" archives and usually been getting my fingers burned
	in various ways.  In one case, I got a second archive, but
	all the branches had disappeared.  Why didn't they come across,
	and what do I need to do to see them?  remote/whatever, perhaps?

	Dave's example might not be exactly what a git expert would
	suggest, but at least it is an easy to follow procedure for
	doing what I need to do.

o	If you don't set up branches correctly, pulling in changes
	from a remote copy of your archive will undo your recent changes
	in your local archive.  Fortunately, I was a bit paranoid by the
	time I tried this, so noticed it while I could still easily
	revert it.

o	Troubleshooting guide.  There is some of this in the various
	"git reset --ripcord" options, but it will be necessary to
	learn the mistakes that dinosaurs such as myself tend to make
	with git, and describe how to detect and fix them.  In contrast,
	the existing troubleshooting guides seem designed for someone
	for whom git is the only source-code control system they have
	known.

> > But my experience is that git is at best an acquired taste for those of
> > us who grew up with traditional source-code control systems.  Such
> > people will benefit greatly from a git-haters guide,...
> 
> "Acquired taste" is a much nicer and more diplomatic way to say the same
> thing as what Linus often refers as "unlearning the braindamage inflicted
> by years of using CVS." ;-)

Heh.  From my viewpoint, CVS is a very recent innovation.  So I am sure
that you meant to write "unlearning the braindamage inflicted by years
of using RCS".  ;-)

Heck, my first source-code-control system was a cabinet full of punched
cards.  No joke.  Another project used a whiteboard -- you wrote down the
names of the files that you were modifying in order to avoid conflicts.

So from my viewpoint, even RCS is a fairly recent innovation.  ;-)

> > ..., and git's user
> > population will grow as a result.
> 
> I do not think it constitutes any basis for judging the merit of having
> the document in git.git tree.  The world domination is not our goal, but
> it may come as a mere side effect of being the best in the business.

Not if almost all of the people who grew up with old technology choke
on git the first time they come across it.  I am here to tell you
that had I not been forced to use git in my work on the Linux kernel,
I would not have given it a second look.  My first several experiences
with it were -extremely- frustrating.  Not necessarily due to bugs
in git (though I might have been running into those, for all I know),
but because it invalidates the intuitions one builds when working with
traditional technology.  One does what comes naturally with git, and
very quickly ends up with a steaming pile of bits.  Which a git expert
could no doubt rescue, but which I was forced to remove and re-clone.

So I suppose I should list some of the things I like about git:

o	It very naturally deals with remote repositories.  If someone
	holds your hand the first time, that is.  ;-)

o	Tagging works very nicely.  In contrast, tagging in RCS is
	quite painful and very easy to get wrong -- to the point that
	I never bothered using it.

	With git, I can easily tag the revision corresponding to a patch
	sent to LKML and then very easily see what I have changed when
	it is time to send the next version.  Very handy and nice.
	I suppose I could do the same thing with branches, and might
	try that next.

o	Moving among various branches works nicely -- as long as you
	know the name of all the branches you need to know about.

o	The "git diff" command usually does what I want with a minimum
	of information -- though it sometimes feels the need to list
	out the names of all the files that have not changed, for
	reasons I do not yet understand.  Still, I have often been
	pleasantly surprised when it does what I wanted it to do despite
	my having forgotten to type something I thought was essential.

o	The fact that "git commit" lists all the files that changed but
	are not being committed has saved me much time and trouble.
	As has its listing the names of the files that -are- being
	committed.

o	I have only used "git rebase" a couple of times, but I could
	see that I could come to like it very much.

See?  I am already only partially a git hater!  ;-)

							Thanx, Paul

Re: [PATCH] Simplified GIT usage guide

[Valdis.Kletnieks]

[-- Attachment #1: Type: text/plain, Size: 941 bytes --]

On Thu, 18 Dec 2008 17:27:23 PST, "Paul E. McKenney" said:

> I would be OK with it being in linux-2.6.git rather than git.git,
> if that helps.  Certainly there seems to be room for a description
> of how to use git within the Linux community.

What might help a lot of people (me, for one) would be a cookbook listing
how to do things that those of us on the fringe might want to do. For example:

"type this to pull Linus's tree, and this to bisect it" (I already know how
to do this one, actually)

"type this to pull a linux-next tree, and this to bisect it" (Last time I tried,
the pull went OK, but I couldn't figure out how to give 'git bisect' a
start/end commit that it was happy with).

"'git log foo/bar/baz.c' is your friend if you're chasing a recently added
bug/regression in baz.c"

Hmm... it occurs to me that my only actual use for git is to find a commit
ID so when I whinge to a developer, we're on the same page... ;)



[-- Attachment #2: Type: application/pgp-signature, Size: 226 bytes --]

Re: [PATCH] Simplified GIT usage guide

[Johannes Schindelin]

Hi,

On Thu, 18 Dec 2008, Paul E. McKenney wrote:

> On Fri, Dec 12, 2008 at 07:57:38PM +0100, Johannes Schindelin wrote:
> 
> > On Fri, 12 Dec 2008, David Howells wrote:
> > 
> > >  Documentation/git-haters-guide.txt | 1283 ++++++++++++++++++++++++++++++++++++
> > 
> > I am sure we want to have something like that in git.git.
> 
> So am I.  Except that I am not being sarcastic.  ;-)

Good idea.  Ask somebody to put up some advertisement _against_ her own 
product into their shop window.

Very good idea.

Ciao,
Dscho

P.S.: Can I ask you to shoot yourself in the foot?

P.P.S.: If you are really a Git hater, why are you lurking here?  Go away, 
Subversion is not that bad.

Re: [PATCH] Simplified GIT usage guide

[Paul E. McKenney]

On Fri, Dec 19, 2008 at 03:38:58AM +0100, Johannes Schindelin wrote:
> Hi,
> 
> On Thu, 18 Dec 2008, Paul E. McKenney wrote:
> 
> > On Fri, Dec 12, 2008 at 07:57:38PM +0100, Johannes Schindelin wrote:
> > 
> > > On Fri, 12 Dec 2008, David Howells wrote:
> > > 
> > > >  Documentation/git-haters-guide.txt | 1283 ++++++++++++++++++++++++++++++++++++
> > > 
> > > I am sure we want to have something like that in git.git.
> > 
> > So am I.  Except that I am not being sarcastic.  ;-)
> 
> Good idea.  Ask somebody to put up some advertisement _against_ her own 
> product into their shop window.
> 
> Very good idea.

Actually works fairly well in many cases.  But it is your shop, not mine.
Do what you like.

> Ciao,
> Dscho
> 
> P.S.: Can I ask you to shoot yourself in the foot?

Sure, go ahead.

> P.P.S.: If you are really a Git hater, why are you lurking here?  Go away, 
> Subversion is not that bad.

My friend, you are shooting yourself in the foot.

							Thanx, Paul

Re: [PATCH] Simplified GIT usage guide

[David Howells]

Miklos Vajna <vmiklos@frugalware.org> wrote:

> This is incorrect, a 'blob' contains only the contents of the blob, the
> file mode is stored in the 'tree' object.

It seems I understand GIT's database less well than I thought.

> Is there any reason you hide the tag object?

What's a tag object?

> Using git clone --mirror would be much efficient, I think.

	warthog>man git-clone | grep mirror
	warthog1>

> Here and later below, IIRC -l is the default for local clones.

Okay.

> --bare implies -n.

Obvious.

> Why not using git stash and git stash pop?

I didn't know such existed.  That's why I want a crib sheet.

David

Re: [PATCH] Simplified GIT usage guide

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 472 bytes --]

On Fri, Dec 12, 2008 at 07:02:41PM +0000, David Howells <dhowells@redhat.com> wrote:
> > Is there any reason you hide the tag object?
> 
> What's a tag object?

http://www.kernel.org/pub/software/scm/git/docs/gitglossary.html#def_tag_object

> > Using git clone --mirror would be much efficient, I think.
> 
> 	warthog>man git-clone | grep mirror
> 	warthog1>

It's new in v1.6.0. You can just use git --bare init; git remote
add --mirror in older versions.

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Simplified GIT usage guide

[David Howells]

Miklos Vajna <vmiklos@frugalware.org> wrote:

> > > Is there any reason you hide the tag object?
> > 
> > What's a tag object?
> 
> http://www.kernel.org/pub/software/scm/git/docs/gitglossary.html#def_tag_object

Okay.  I do mention tags.  How they're stored in the database is irrelevant.
As far as most users need be concerned, a tag is a symbolic representation of
a particular commit in the tree; a particular state of the source tree.

Think of symbolic links as an analogy.  Most users just need to know that a
symlink represents the location of another part of the VFS tree; actually most
users will just think of them as a pointer to the name of a file, if even that
much.  The fact that, say, ReiserFS tail packs them because they tend to be
small, or that AFS symlinks have weird properties that encode mountpoints is
irrelevant to most users.  You don't need to know that to use them.

Yes, GIT's database has blob objects, tree objects, commit objects and tag
objects; but as far as the normal user is concerned, it stores files, lists of
files (directories or, more probably, folders), commits and tags.  The
physical low-level stuff is completely irrelevant.

There is one exception to that: commit IDs.  These are public-facing as it
were.  GIT waves them in your face, and you have to use them occasionally, so
it's useful to say a bit about them.

David

Re: [PATCH] Simplified GIT usage guide

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 1404 bytes --]

On Sat, Dec 13, 2008 at 01:12:56AM +0000, David Howells <dhowells@redhat.com> wrote:
> Okay.  I do mention tags.  How they're stored in the database is irrelevant.
> As far as most users need be concerned, a tag is a symbolic representation of
> a particular commit in the tree; a particular state of the source tree.

Actually I think it matters, that's why a 'tag' differs to a 'tag
object'. Also, a tag can point to any other object, not just to a
commit. (Though usually it does.)

> Think of symbolic links as an analogy.  Most users just need to know that a
> symlink represents the location of another part of the VFS tree; actually most
> users will just think of them as a pointer to the name of a file, if even that
> much.  The fact that, say, ReiserFS tail packs them because they tend to be
> small, or that AFS symlinks have weird properties that encode mountpoints is
> irrelevant to most users.  You don't need to know that to use them.

Won't it be confusing that a symlink can be stored as a blob, tags are
refs, but refs are not blobs?

> Yes, GIT's database has blob objects, tree objects, commit objects and tag
> objects; but as far as the normal user is concerned, it stores files, lists of
> files (directories or, more probably, folders), commits and tags.  The
> physical low-level stuff is completely irrelevant.

Agreed, the object database is not interesting for a beginner.

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Simplified GIT usage guide

[David Howells]

Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

> > +I don't really know what I'm doing with GIT either.
> 
> Strike the "either".

The whole point of the introduction is that this is aimed at someone who
doesn't know what they're doing, so IMO the "either" is quite correct here.

> > +===============
> > +OVERVIEW OF GIT
> > +===============
> 
> Your overview seems to be what "Git from the bottom up" is all about (see 
> the Git Wiki for more information where to find it).

The problem is I need to describe some terminology, and the best way to do
that is with some pictures.  I was wondering if I should break this out into a
separate document and simplify what I keep.

In my opinion, it's much easier to deal with if you can visualise how it
works, even if that visualisation isn't a true representation of reality,
which references Miklos's points.

> From my experience with new users, this is exactly the wrong way to go 
> about it.  You don't introduce object types of the Git database before 
> telling the users what the heck they are good for.  And most users do not 
> need to bother with tree objects either, anyway.  So maybe you just tell 
> them what the heck the object types are good for, without even teaching 
> them the object types at all.

Perhaps.  The main thing I want to introduce is the idea of a tree with three
levels, as it were: commits, directories, files.

> So I think that your document might do a good job scaring people away from 
> Git.  But I do not believe that your document, especially in the tone it 
> is written, does a good job of helping Git newbies.

Hmmm.  So what would you suggest is a good way to write for GIT newbies?  Is
it just that the overview should be canned or drastically simplified?

David

Re: [PATCH] Simplified GIT usage guide

[Sverre Rabbelier]

On Fri, Dec 12, 2008 at 20:12, David Howells <dhowells@redhat.com> wrote:
> In my opinion, it's much easier to deal with if you can visualise how it
> works

Ah, this is of course why they teach you how an engine works at the
driving schools!

-- 
Cheers,

Sverre Rabbelier

Re: [PATCH] Simplified GIT usage guide

[Aidan Van Dyk]

[-- Attachment #1: Type: text/plain, Size: 945 bytes --]

* Sverre Rabbelier <alturin@gmail.com> [081201 00:00]:
> On Fri, Dec 12, 2008 at 20:12, David Howells <dhowells@redhat.com> wrote:
> > In my opinion, it's much easier to deal with if you can visualise how it
> > works
> 
> Ah, this is of course why they teach you how an engine works at the
> driving schools!

No, but all the people I've taught to drive have suddenly "got it" after
a gentle introduction as to how the clutch clutch and engine speed work
together in the transmission to accellerate/decellerate the car...

So, a bit of "understanding" of what's actually going on helped them,
not the "push that pedal towards the floor and pop the other one out!".

But... everyone learns differently...

a.

-- 
Aidan Van Dyk                                             Create like a god,
aidan@highrise.ca                                       command like a king,
http://www.highrise.ca/                                   work like a slave.

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] Simplified GIT usage guide

[Nick Andrew]

On Fri, Dec 12, 2008 at 07:12:13PM +0000, David Howells wrote:
> Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

> > So I think that your document might do a good job scaring people away from 
> > Git.  But I do not believe that your document, especially in the tone it 
> > is written, does a good job of helping Git newbies.
> 
> Hmmm.  So what would you suggest is a good way to write for GIT newbies?  Is
> it just that the overview should be canned or drastically simplified?

The way I did it was to start with the directed acyclic graph of
commits, explaining how branches fork the graph and merges join
it. This was presented to people who know subversion, and so they
immediately became aware that there are other ways to manage source
code than in a linear r1 r2 r3 r4 r5. I described tags and branch
heads briefly.

Next up I described the things you'd do with git: add new commits,
create a branch, merge a branch, rebase, tag, push and fetch and
showed what that does with the dag of commits.

Finally I showed the actual commands used to perform those actions.
I didn't get into the object database structure at all (that was
prepared in case I had extra time).

I think a tutorial shouldn't be written in a way that polarises
peoples' opinions or they come to regard git as a "necessary evil".
If the audience is a person who knows nothing about git, that's
hardly a "git hater" and I think the document starts off on the
wrong foot as a result.

Nick.

Re: [PATCH] Simplified GIT usage guide

[Ping Yin]

On Sun, Dec 14, 2008 at 7:05 AM, Nick Andrew <nick@nick-andrew.net> wrote:
> The way I did it was to start with the directed acyclic graph of
> commits, explaining how branches fork the graph and merges join
> it. This was presented to people who know subversion, and so they
> immediately became aware that there are other ways to manage source
> code than in a linear r1 r2 r3 r4 r5. I described tags and branch
> heads briefly.
>
> Next up I described the things you'd do with git: add new commits,
> create a branch, merge a branch, rebase, tag, push and fetch and
> showed what that does with the dag of commits.
>
> Finally I showed the actual commands used to perform those actions.
> I didn't get into the object database structure at all (that was
> prepared in case I had extra time).
>

I think this is the right way to start with the DAG. And i do the same.

Re: [PATCH] Simplified GIT usage guide

[Jakub Narebski]

David Howells <dhowells@redhat.com> writes:

> Add a guide to using GIT's simpler features.

Wouldn't it be better to update either "Git User's Manual",
or http://book.git-scm.com?

See also: http://git.or.cz/gitwiki/GitDocumentation (including "Git
Magic", "Git in Nutshell", "Git for computer scientists" and "Git from
bottoms up"
-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: [PATCH] Simplified GIT usage guide

[J. Bruce Fields]

On Fri, Dec 12, 2008 at 06:28:27PM +0000, David Howells wrote:
> Add a guide to using GIT's simpler features.
> 
> Signed-off-by: David Howells <dhowells@redhat.com>

Just a couple random thoughts:

	- The advantage of adding this to the kernel tree is that you
	  can tailor it for a more specific audience (kernel developers
	  and testers).  A lot of this (e.g. the object-database
	  discussion) seems to be generic introduction-to-git stuff.
	  Is there some canonical external documentation you could refer
	  to for that stuff, that would allow you to get more quickly to
	  the more tailored information?  If not, is there something you
	  could improve to the point where you *would* be comfortable
	  referring to it?
	- How much overlap is there with
	  Documentation/development-process/7.AdvancedTopics?  Should
	  there be cross-references between the two?

There's an awful lot of introductions to git out there now (and I've got
my own share of the blame).

--b.

> ---
> 
>  Documentation/git-haters-guide.txt | 1283 ++++++++++++++++++++++++++++++++++++
>  1 files changed, 1283 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/git-haters-guide.txt
> 
> 
> diff --git a/Documentation/git-haters-guide.txt b/Documentation/git-haters-guide.txt
> new file mode 100644
> index 0000000..51e4dac
> --- /dev/null
> +++ b/Documentation/git-haters-guide.txt
> @@ -0,0 +1,1283 @@
> +		      ===================================
> +		      THE GIT HATER'S GUIDE TO THE GALAXY
> +		      ===================================
> +
> +By David Howells <dhowells@redhat.com>
> +
> +Contents:
> +
> + (*) Introduction.
> +
> +     - Disclaimer.
> +
> + (*) Overview of GIT.
> +
> +     - Git objects.
> +     - Symbolic pointers.
> +     - The GIT tree.
> +     - GIT trees after merging.
> +
> + (*) Downloading upstream trees.
> +
> +     - Local mirroring.
> +     - Automatic updates.
> +     - Using your local mirror.
> +
> + (*) Accessing the repository.
> +
> +     - Viewing the history.
> +     - Viewing a commit.
> +     - Viewing source differences.
> +
> + (*) Making changes.
> +
> +     - Applying patches.
> +     - Applying formatted patches.
> +     - Incorporating GIT trees.
> +
> + (*) Amending and reverting changes.
> +
> +     - Amending committed changes.
> +     - Discarding committed changes.
> +     - Reverting committed changes.
> +
> + (*) Publishing changes by GIT tree.
> +
> +     - Setting up.
> +     - Updating your development tree.
> +     - Publishing your changes.
> +
> + (*) Manually merging failed fetches.
> +
> + (*) Locating bugs.
> +
> +     - Bisection.
> +     - Blame.
> +
> +
> +============
> +INTRODUCTION
> +============
> +
> +So, you want to do some Linux kernel development?  And you hear there's this
> +piece of software called 'GIT' that you probably ought to be using when dealing
> +with the kernel community?  Then you find out that not only was Linux started
> +by this Linus Torvalds person, but GIT was too!  Perhaps it doesn't seem fair:
> +Linus has not just _one_ huge piece of software named after himself, but _two_!
> +And on top of that, globe spanning hardware vendors just queue up to give him
> +all the herring he can eat!!
> +
> +Then you look at webpages about GIT.  You look at the manpages!  You run the
> +commands with --help!  And you *still* don't know how to do anything complex
> +with it!!  You feel certain that there's some secret rite you have to perform
> +to become a GIT initiate - probably something involving two goats, an altar and
> +a full moon - oh, and lots of beer (we *are* talking about kernel developers
> +after all).
> +
> +Then you ask around, and people look at you blankly, hedge or say that it's
> +easy and obvious (they should know - they wrote the damned thing).  You realise
> +that the manpages are more an aide-memoire and that what you really want is
> +some sort of crib sheet; something that can hold your hand whilst you cut and
> +paste things from of it until you can see the point.
> +
> +Well, let's see if I can help...
> +
> +
> +DISCLAIMER
> +----------
> +
> +I don't really know what I'm doing with GIT either.  I'm not sure anyone really
> +does, apart from Linus (and then only after some strange Finnish snack
> +involving red and white mushrooms).  If you'd pause to wonder why things are
> +like they are, you'd realise that only someone totally barking would try to
> +write a kernel in the first place... and then it'd dawn on you what the mental
> +state must be like of someone who'd try writing something like a source code
> +management system from scratch...  and then you'd consider what it must take to
> +be someone who'd do *both*.
> +
> +
> +===============
> +OVERVIEW OF GIT
> +===============
> +
> +GIT is a source code management system.  You give it your sources to retain,
> +and it manages the history of all the changes and provides you with a set of
> +tools by which that history can be viewed, extracted and extended.
> +
> +GIT is unusual in its design in that the objects it retains are referred to by
> +hashes of their content.  Because it is mathematically possible for object IDs
> +to collide, large hash IDs are used to reduce the probability of a collision.
> +If the content of an object changes, rather than updating the existing object,
> +GIT will create a new object with a new hash ID.  Objects are _invariant_.
> +
> +The GIT database in a GIT tree has two sets of data:
> +
> + (1) A set of objects, indexed by the object hash ID.
> +
> + (2) A set of symbolic object tree heads, as object hash IDs.
> +
> +
> +GIT OBJECTS
> +-----------
> +
> +There are three basic types of object:
> +
> + (1) File objects.
> +
> +     A file object contains the contents of a source file and the attributes of
> +     that file (such as file mode).
> +
> + (2) Directory objects.
> +
> +     A directory object contains the attributes of that directory plus a list
> +     of file and directory objects that are members of this directory.  The
> +     list includes the names of the entries within that directory and the
> +     object ID of each object.
> +
> + (3) Commit objects.
> +
> +     A commit object contains the attribute of that commit (the author and the
> +     date for instance), a textual description of the change imposed by that
> +     commit as provided by the committer, a list of object IDs for the commits
> +     on which this commit is based, and the object ID of the root directory
> +     object representing the result of this commit.
> +
> +     Note that a commit does not literally describe the changes that have been
> +     made in the way that, say, a diff file does; it merely carries the current
> +     state of the sources after that change, and points to the commits that
> +     describe the state of the sources before that change.  GIT's tools then
> +     infer the changes when asked.
> +
> +     A commit object will typically refer to one base commit when someone has
> +     merely committed some changes on top of the current state, and two base
> +     commits when a couple of trees have been merged.
> +
> +Because objects are invariant, and because they can thus be referred to by a
> +hash of their contents, objects can be shared between trees simply by using the
> +same object ID in two different places.  This allows objects to be compared to
> +see whether they are the same thing or not simply by comparing the object ID.
> +
> +
> +SYMBOLIC POINTERS
> +-----------------
> +
> +GIT retains its historical information in a set of overlapping, shared trees,
> +but the notion of where a tree starts isn't really a primary concept with GIT.
> +What it has instead is a number of symbolic pointers to commits within the tree
> +that are considered to be of some sort of significance.  These are called
> +'heads' and include:
> +
> + (1) The base for the current working state of the checked out sources (HEAD).
> +
> + (2) Branches (by branch name).
> +
> + (3) Tags (by tag name).
> +
> + (4) Merge base (for incomplete merges).
> +
> + (5) Points of interest, such as those that pertain to a git fetch (FETCH_HEAD
> +     and ORIG_HEAD).
> +
> + (6) Bisection points (when bisection is being used to find a bug).
> +
> +In essence, these symbolic pointers are just names or conventions for
> +particular roots in the tree.  They are a name that maps to the object ID of a
> +commit object.
> +
> +Some of them have special meanings, such as branches, that can be configured to
> +behave in various ways under certain conditions (such as when a git fetch is
> +performed).
> +
> +
> +THE GIT TREE
> +------------
> +
> +The GIT tree in its simplest terms is a backbone of commits that point to
> +directories that point to files.  To give a simple example of the commit
> +process, consider the sources for a project that contains one directory, D,
> +which contains three files, F1, F2 and F3.
> +
> +This could then be committed into GIT to begin a project, in this case as
> +commit C0.  This would hold version D0 of the directory, and versions F1A, F2A
> +and F3A of the three files, and the GIT repository HEAD pointer would point to
> +C0:
> +
> +	                                        +-----+
> +	                                    +-->| F3A |
> +	                                    |   +-----+
> +	                                    |
> +	        +-----+        +-----+      |   +-----+
> +	HEAD--->| C0  |------->| D0  |------+-->| F2A |
> +	        +-----+        +-----+      |   +-----+
> +	                                    |
> +	                                    |   +-----+
> +	                                    +-->| F1A |
> +	                                        +-----+
> +
> +Now imagine that someone changes file F2 and commits the change.  F1A and F3A
> +are still useful, and can be shared by the new view of the world, but F2 is now
> +on a new version, F2B.  The old directory object, D0, pointed to F2A, so that
> +cannot be reused, and so D1 is generated.  The commit process then writes a new
> +commit object, C1, that points to D1 as the state of the tree after this
> +commit, and points to C0 as the commit on which C1 was based.  Finally, HEAD is
> +changed to point to C1.
> +
> +	                                        +-----+
> +	                                  +---->| F2B |
> +	        +-----+        +-----+    |     +-----+
> +	HEAD--->| C1  |------->| D1  |----+
> +	        +-----+        +-----+    |
> +	           |                      |
> +	           |                      |     +-----+
> +	           |                      +---->| F3A |
> +	           |                      | +-->+-----+
> +	           V                      | |
> +	        +-----+        +-----+    | |   +-----+
> +	        | C0  |------->| D0  |------+-->| F2A |
> +	        +-----+        +-----+    | |   +-----+
> +	                                  | |
> +	                                  +-|-->+-----+
> +	                                    +-->| F1A |
> +	                                        +-----+
> +
> +Then imagine that someone changes file F1 and commits the change.  F3A is still
> +viable in its original state, and F2B is usable from commit C1, but F1A is now
> +obsolete and gets replaced by version F1B.  This means that neither D0 nor D1
> +are usable, so directory object D2 has to be created, and new commit C2 is
> +created to point to that and base commit C1.  Then HEAD is set to point to C2:
> +
> +	                                        +-----+
> +	                                +------>| F1B |
> +	        +-----+        +-----+  |       +-----+
> +	HEAD--->| C2  |------->| D2  |--+
> +	        +-----+        +-----+  |
> +	           |                    |
> +	           |                    +------>+-----+
> +	           V                    | +---->| F2B |
> +	        +-----+        +-----+  | |     +-----+
> +	        | C1  |------->| D1  |----+
> +	        +-----+        +-----+  | |
> +	           |                    | |
> +	           |                    +-|---->+-----+
> +	           |                      +---->| F3A |
> +	           |                      | +-->+-----+
> +	           V                      | |
> +	        +-----+        +-----+    | |   +-----+
> +	        | C0  |------->| D0  |------+-->| F2A |
> +	        +-----+        +-----+    | |   +-----+
> +	                                  | |
> +	                                  +-|-->+-----+
> +	                                    +-->| F1A |
> +	                                        +-----+
> +
> +Now, consider what would have happened if, instead of changing F1A to be F1B to
> +produce C2, F2B had been reverted to the same state as F2A.  GIT would realise
> +that it already has a file object to represent F2A (by comparing object IDs)
> +and would use that rather than creating a new one.  The new set of files in the
> +directory would then be F1A, F2A and F3A - but there's already a directory
> +object for that: D0.  This would also be discovered by object ID matching, and
> +would be used instead.  Commit C3 would then point to base commit C1 and
> +directory D0, and HEAD would be moved to point to C3:
> +
> +	        +-----+
> +	HEAD--->| C3  |---+
> +	        +-----+   |
> +	           |      |
> +	           |      |                     +-----+
> +	           V      |               +---->| F2B |
> +	        +-----+   |    +-----+    |     +-----+
> +	        | C1  |------->| D1  |----+
> +	        +-----+   |    +-----+    |
> +	           |      |               |
> +	           |      |               |     +-----+
> +	           |      |               +---->| F3A |
> +	           |      |               | +-->+-----+
> +	           V      |               | |
> +	        +-----+   +--->+-----+    | |   +-----+
> +	        | C0  |------->| D0  |------+-->| F2A |
> +	        +-----+        +-----+    | |   +-----+
> +	                                  | |
> +	                                  +-|-->+-----+
> +	                                    +-->| F1A |
> +	                                        +-----+
> +
> +
> +GIT TREES AFTER MERGING
> +-----------------------
> +
> +Now, imagine that two GIT trees are merged.  You start off with two sets of
> +commits (for convenience, I'm going to leave out the directories and files, but
> +you can just assume they're there):
> +
> +	        +-----+                         +-----+
> +	HEAD--->| C3  |                 Branch->| B3  |
> +	        +-----+                         +-----+
> +	           |                               |
> +	           V                               V
> +	        +-----+                         +-----+
> +	        | C2  |                         | B2  |
> +	        +-----+                         +-----+
> +	           |                               |
> +	           V                               V
> +	        +-----+                         +-----+
> +	        | C1  |<------------------------| B1  |
> +	        +-----+                         +-----+
> +	           |
> +	           V
> +	        +-----+
> +	        | C0  |
> +	        +-----+
> +
> +In the above example, I've assumed that you've got your own tree with the head
> +at commit C3, and that you've got a branch that you want to merge, which has
> +its head at commit B3.  After merging them, you'd end up with a directed,
> +cyclic tree:
> +
> +	        +-----+
> +	HEAD--->| C4  |----------------------------+
> +	        +-----+                            |
> +	           |                               |
> +	           V                               V
> +	        +-----+                         +-----+
> +	        | C3  |                 Branch->| B3  |
> +	        +-----+                         +-----+
> +	           |                               |
> +	           V                               V
> +	        +-----+                         +-----+
> +	        | C2  |                         | B2  |
> +	        +-----+                         +-----+
> +	           |                               |
> +	           V                               V
> +	        +-----+                         +-----+
> +	        | C1  |<------------------------| B1  |
> +	        +-----+                         +-----+
> +	           |
> +	           V
> +	        +-----+
> +	        | C0  |
> +	        +-----+
> +
> +and the C4 commit will have pointers to *both* contributing commits, C3 and B3.
> +If GIT stored the differences at each commit rather than the terminal state, it
> +would have to store a delta for each contributing commit.
> +
> +
> +==========================
> +DOWNLOADING UPSTREAM TREES
> +==========================
> +
> +The first thing you'll usually want to do with GIT is to grab a copy of the
> +cutting edge version of an upstream project and build it; perhaps you want to
> +work on it, perhaps because it has a fix in it that you need or perhaps because
> +you like living on the cutting edge and enjoy grepping your disks to recover
> +your data when things go wrong.  Whatever your reasons, you need to be able
> +make a local copy of an upstream GIT tree.
> +
> +With GIT-based projects, grabbing a local copy of an upstream repository is
> +very easy:
> +
> +	git clone %UPSTREAM_REPO %MY_DIR
> +
> +This will create a checked-out copy of the the upstream repository
> +(%UPSTREAM_REPO) by pulling over the internet and sticking it in a directory on
> +the local machine.
> +
> +For example, to fetch Linus's cutting edge kernel tree, you'd do:
> +
> +	git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git \
> +		linux-2.6-local
> +
> +Then you look in linux-2.6-local and there is what you're looking for.
> +
> +
> +LOCAL MIRRORING
> +---------------
> +
> +You might find that you wish to run several concurrent, separate developments
> +all based upon a single upstream repository.  You could simply clone each one
> +as mentioned above, but that has the potential to use excessive amounts of disk
> +space as each clone would include an independent copy of the entire source
> +repository.
> +
> +What you might want to do is to set up a mirror of the upstream repository, and
> +then share that mirror with each of the clones.  Even better, you can share it
> +with other people who can also access the filesystem it is stored upon.
> +
> +So what you can do is create a local mirror:
> +
> +	git clone -n %UPSTREAM_REPO %MIRROR_DIR
> +
> +For example:
> +
> +	git clone -n git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git \
> +		/warthog/git/linux-2.6.git
> +
> +The -n flag tells git to save space by not bothering to check the files out of
> +the repository.  You don't really need the checkout if all you're going is to
> +use this as a reference, but you can still check out if you like by omitting
> +the -n.
> +
> +
> +AUTOMATIC UPDATES
> +-----------------
> +
> +Furthermore, you might want to automatically update your sources at some
> +unfeasible hour of the morning when only Australians are awake because, say,
> +your internet supply is rated more cheaply then - but you don't necessarily
> +want the automatic update to dump into the sources you're actively meddling
> +with.  A local mirror can help with this too.
> +
> +One way of automatically updating your mirror is to use cron.  To do this
> +create a script that looks something like:
> +
> +	#!/bin/sh
> +	cd %MIRROR_DIR || exit $?
> +	exec git pull >/tmp/git-pull.log
> +
> +and chmod u+x it.  Then run the crontab program to modify your personal cron
> +schedule and add something like the following line to it (not forgetting to
> +remove the leading tab!):
> +
> +	0 %HOUR * * *       %MIRROR_SCRIPT
> +
> +where %HOUR is the hour you want it to go off every day.  For my local mirror
> +of Linus's upstream kernel, I use:
> +
> +	#!/bin/sh
> +	cd /warthog/git/linux-2.6 || exit $?
> +	exec git pull >/tmp/git-pull.log
> +
> +and:
> +
> +	0 6 * * *       /home/dhowells/bin/do-git-pull.sh
> +
> +which will do the update every day at 6am.
> +
> +
> +USING YOUR LOCAL MIRROR
> +-----------------------
> +
> +You can then create a directory to actually do your development in by:
> +
> +	git clone -l -s %MIRROR_DIR %MY_DIR
> +
> +The "-l" tells git clone that the source (mirror) repository is on the local
> +machine, that it shouldn't go over the internet for it, and that it should
> +hardlink GIT objects from the source repository rather than copying them where
> +possible.
> +
> +The "-s" says that git clone should insert a reference under %MY_DIR that
> +points to the %MIRROR_DIR's collection of objects.  This means that GIT won't
> +bother to copy the objects that it can get from %MIRROR_DIR at all, it'll just
> +use them out of %MIRROR_DIR.
> +
> +    [!] NOTE: This makes %MY_DIR dependent on %MIRROR_DIR: if you delete
> +    	%MIRROR_DIR or prune it you may make %MY_DIR unusable!
> +
> +You can repeat this again and again from the same mirror.  You can even share a
> +mirror with other people that can access the filesystem holding the mirror.
> +You don't need write access to it, only read.
> +
> +
> +========================
> +ACCESSING THE REPOSITORY
> +========================
> +
> +One of the things you'll want to be able to do with what you've downloaded is
> +look at changes other people have made.  GIT has some powerful tools to allow
> +you to do this.
> +
> +
> +VIEWING THE HISTORY
> +-------------------
> +
> +You might wish, for example, to look back through the commit tree and see what
> +changes have been made.  The command to do this is:
> +
> +	git log
> +
> +This will take you back through the commit information, starting at the current
> +HEAD and going all the way back to the beginning if you let it:
> +
> +	warthog>git log
> +	commit 8b1fae4e4200388b64dd88065639413cb3f1051c
> +	Author: Linus Torvalds <torvalds@linux-foundation.org>
> +	Date:   Wed Dec 10 15:11:51 2008 -0800
> +
> +	    Linux 2.6.28-rc8
> +
> +	commit f9fc05e7620b3ffc93eeeda6d02fc70436676152
> +	Merge: b88ed20... 9a2bd24...
> +	Author: Linus Torvalds <torvalds@linux-foundation.org>
> +	Date:   Wed Dec 10 14:41:06 2008 -0800
> +
> +	    Merge branch 'sched-fixes-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/linux-2.6-tip
> +
> +	    * 'sched-fixes-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/linux-2.6-tip:
> +	      sched: CPU remove deadlock fix
> +
> +	commit b88ed20594db2c685555b68c52b693b75738b2f5
> +	Author: Hugh Dickins <hugh@veritas.com>
> +	Date:   Wed Dec 10 20:48:52 2008 +0000
> +	...
> +
> +
> +VIEWING A COMMIT
> +----------------
> +
> +Now that you can see the commit IDs in the history, you can examine one more
> +closely:
> +
> +	git show
> +
> +to see the current HEAD commit, or:
> +
> +	git show %COMMIT_ID
> +
> +to see a particular commit:
> +
> +	warthog>git show 1da177e
> +	commit 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2
> +	Author: Linus Torvalds <torvalds@ppc970.osdl.org>
> +	Date:   Sat Apr 16 15:20:36 2005 -0700
> +
> +	    Linux-2.6.12-rc2
> +
> +	    Initial git repository build. I'm not bothering with the full history,
> +	...
> +	diff --git a/COPYING b/COPYING
> +	new file mode 100644
> +	index 0000000..2a7e338
> +	--- /dev/null
> +	+++ b/COPYING
> +	@@ -0,0 +1,356 @@
> +	+
> +	+   NOTE! This copyright does *not* cover user programs that use kernel
> +	...
> +
> +
> +VIEWING SOURCE DIFFERENCES
> +--------------------------
> +
> +The 'git-show' command shows you what it thinks the differences are that you
> +want to see, between a commit and its first listed base commit.  However, there
> +are other differences you might wish to see.
> +
> +Firstly, you might like to see the differences between what's in the current
> +HEAD commit, and what you've got checked out:
> +
> +	git diff
> +
> +or you might wish to see the differences between two particular commits, for
> +example:
> +
> +	git diff v2.6.24 v2.6.25
> +
> +
> +==============
> +MAKING CHANGES
> +==============
> +
> +So you've got a fresh development GIT tree and you want to make changes in it
> +and commit them to it.  The first is easy enough: just use your preferred text
> +editor to edit the files directly, or you could use sed or perl to apply some
> +textual transformations - that's entirely up to you.
> +
> +However, once you've made those changes and you've compiled and tested them,
> +you'll probably want to consign them to GIT.
> +
> +Files you've added must be marked by:
> +
> +	git add <filename>
> +
> +and files you've deleted must be noted by:
> +
> +	git rm <filename>
> +
> +so that GIT knows to include or exclude these files from its tree.
> +Furthermore, you must tell GIT about any files that have changed that you want
> +to be updated also:
> +
> +	git add <filename>
> +
> +You can then commit your changes.  This is done by running:
> +
> +	git commit
> +
> +Rather than doing lots of git add and git rm commands to register updated and
> +removed files, you can give git commit a '-a' flag.  Note, though, that this
> +takes no account of new files that git doesn't already know about.  Those must
> +be added manually.
> +
> +git commit will pop up your favourite editor, asking you to enter a commit
> +message describing your changes (don't forget to add your sign-off).  It will
> +list the files it sees that have been added, altered and removed, and will
> +differentiate between those that it has been told about (and thus will include)
> +and those it hasn't (which will be ignored).
> +
> +After git commit completes successfully, 'git show' should show the new commit
> +you've just made, and gitk should show the new tree structure with your new
> +commit at the top.
> +
> +
> +APPLYING PATCHES
> +----------------
> +
> +If you have a patch file you wish to apply, you can do that with:
> +
> +	git apply <patch-file>
> +
> +This will make the changes specified by the patch, but it won't register any of
> +the changes and won't record any of the metadata that might be in the patch
> +file, such as authorship, description or attribution.  That has to be done
> +manually as if you'd made the changes yourself.
> +
> +
> +APPLYING FORMATTED PATCHES
> +--------------------------
> +
> +Sometimes you may wish to incorporate a patch that someone has emailed you.
> +You could use the 'patch' or 'git apply' programs and then set up the commit
> +information manually, but if someone has sent you an appropriately formatted
> +message - perhaps in an email - you can have GIT import the metadata from the
> +message rather than you having to type it manually.
> +
> +If someone has given you an email or appropriately formatted patch file, the
> +following command can import it:
> +
> +	git am <patch-file>
> +
> +If successful, this will automatically register all added, altered and removed
> +files and commit the changes for you.  The commit message will be concocted
> +from the description and email headers (From: and Subject: for instance).  If
> +you want to add your own sign-off to the bottom of the commit message whilst
> +you're at it, you can add a '-s' flag:
> +
> +	git am -s <patch-file>
> +
> +You may find it convenient to edit unformatted patches to make it possible to
> +use 'git am' rather than 'git apply'.
> +
> +
> +INCORPORATING GIT TREES
> +-----------------------
> +
> +And sometimes, rather then sending you patches, people may attempt to
> +contribute changes to you that are contained within GIT trees and you may wish
> +to incorporate these into your development tree.
> +
> +To do this, the following command will work:
> +
> +	git pull %CONTRIB_REPO %CONTRIB_BRANCH
> +
> +where %CONTRIB_REPO is the URL of a repository and %CONTRIB_BRANCH is the name
> +of the branch within that repository (usually this will be 'master').
> +
> +If successful, this will either just stack the pulled changes directly on top
> +of your tree (assuming the contributed tree is based on the head of your tree)
> +or it will automatically produce a merge commit indicating that the resulting
> +tree is a union of the changes in your tree and the contributed tree.
> +
> +If unsuccessful due to conflicting changes, you'll need to perform the merge
> +manually and perform the commit yourself.  See the "Manually merging failed
> +fetches" section.
> +
> +An example of the command line you might use is:
> +
> +	git pull git://git.infradead.org/mtd-2.6.git master
> +
> +which will pull master branch of the upstream MTD tree into the GIT tree you're
> +currently in.
> +
> +
> +==============================
> +AMENDING AND REVERTING CHANGES
> +==============================
> +
> +There will be times when you make a mistake in your changes, and you find that
> +you either want to amend them, or you want to discard them entirely.  GIT
> +provides a number of tools to do this.
> +
> +If you make a mistake in changes you haven't yet committed, you can just edit
> +them again with your text editor, or if you'd prefer to discard all the changes
> +you made to a particular file, you can do:
> +
> +	git checkout <filename>
> +
> +This will just wipe away the changes that you've made and restore the file to
> +the state it has recorded for it as part of the topmost commit.
> +
> +
> +AMENDING COMMITTED CHANGES
> +--------------------------
> +
> +If you've committed some changes and you realise that those changes are
> +incorrect, you can amend them without precisely making a whole new commit -
> +provided you haven't committed anything else on top of them.
> +
> +To do this, you make your changes, run git add and git rm as normal, and then
> +do:
> +
> +	git commit --amend
> +
> +This will replace the topmost commit with a similar commit that includes the
> +amendments.  The old commit will be displaced from the tree and will not appear
> +again.
> +
> +Changes that are buried beneath further commits unfortunately have to be
> +altered by making a new commit with the amendments, unless you wish to discard
> +all the commits down to the one that needs amending, and then apply them all
> +again.
> +
> +
> +DISCARDING COMMITTED CHANGES
> +----------------------------
> +
> +Upon occasion, you'll want to discard one or more commits entirely from the top
> +of your tree.  To do this you need to find the ID of the latest commit that you
> +want to keep.  Everything from the commit after that to the current commit will
> +be discarded.
> +
> +You can find the commit ID in a number of ways.  Firstly, you can use 'git log'
> +to look back through the commits.  The commit ID is shown as something like:
> +
> +	commit 6c34bc2976b30dc8b56392c020e25bae1f363cab
> +
> +Secondly, you can use gitk: select the commit of interest; the commit ID
> +appears in the box labelled "SHA1 ID".
> +
> +You can then perform the discard with the following command:
> +
> +	git reset --hard %COMMIT_ID
> +
> +Using the above commit ID as an example, you could do:
> +
> +	git reset --hard 6c34bc2976b30dc8b56392c020e25bae1f363cab
> +
> +
> +REVERTING COMMITTED CHANGES
> +---------------------------
> +
> +And sometimes you'll want to revert changes that you've committed, but that are
> +now buried beneath other commits.  Short of discarding and reapplying commits,
> +you have to apply a reverse patch:
> +
> +	git diff %COMMIT_ID | patch -p1 -R
> +
> +and then commit it.  Both the original application and the reversion will be
> +retained by GIT.
> +
> +
> +==============================
> +PUBLISHING CHANGES BY GIT TREE
> +==============================
> +
> +Now that you've got a tree and have mangled it in unspeakable ways, you
> +probably want to donate the glory of your works back to the community - usually
> +with an eye to getting your changes pulled into an upstream maintainer's
> +repository.  Your upstream maintainer may then push your changes on to their
> +upstream maintainer, until it ends into the ultimate upstream repository
> +(Linus's linux-2.6 tree in the case of the Linux kernel).
> +
> +You could, of course, just push patches to the upstream maintainer, be that
> +Linus or one of his cronies in the case of the Linux kernel, or some other
> +person if some other project.
> +
> +GIT, however, leans strongly towards another option.  If you can get access to
> +a computer that is accessible by way of the internet, you might be able to set
> +up a public GIT tree upon it and ask an appropriate upstream maintainer to pull
> +from that.
> +
> +That computer, however, may not be particularly convenient for developing on:
> +it may be remote from where you're working, for example, perhaps even on a
> +different continent - so you'll probably want to have two trees: a remote,
> +public, published tree, and a local private tree where you can break stuff at
> +will.  I'm going to assume the two trees approach.
> +
> +
> +SETTING UP
> +----------
> +
> +First of all, you'll need to set up your two trees.  There are a number of
> +steps to go through to do this:
> +
> + (1) Find somewhere that's accessible by the internet (%REMOTE_BOX) that you
> +     have SSH access to, and set up a public GIT tree that's a clone of the
> +     upstream tree you want to use as a base:
> +
> +	ssh %REMOTE_BOX
> +	cd /my/git/trees
> +	git clone -n --bare %UPSTREAM_REPO %MY_DIR
> +
> +     Where %UPSTREAM_REPO is something like:
> +
> +	git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
> +
> +     This will create a directory called /my/git/trees/%MY_DIR that contains a
> +     bare GIT repository to which you can upload your changes.  There will be
> +     no checked out files here, and everything that would usually be in the
> +     .git directory is in the top directory instead.
> +
> +     If your tree is on the same box as the tree you want to fork, you can
> +     tell GIT to use that rather than going to the internet:
> +
> +	git clone -l -s -n --bare %UPSTREAM_DIR %MY_DIR
> +
> +     For example, I might wish to set up a tree to publish NOMMU changes so
> +     that they're available through git.kernel.org.  To that end, I would do:
> +
> +	ssh master.kernel.org
> +	cd /pub/scm/linux/kernel/git/dhowells
> +	git clone -l -n -s --bare \
> +		/pub/scm/linux/kernel/git/torvalds/linux-2.6.git linux-2.6-nommu
> +
> +
> + (2) You should set the description on your public repository:
> +
> +	echo %DESCRIPTION >%MY_DIR/description
> +
> +     For example:
> +
> +	echo "NOMMU development" >linux-2.6-nommu/description
> +
> +     This will be published through the GIT web interface if one is set up, and
> +     so can be viewed by going to the appropriate URL.  For instance:
> +
> +	http://git.kernel.org/?p=linux/kernel/git/dhowells/linux-2.6-nommu.git
> +
> +
> + (3) Now go to the work machine on which you'll be doing your development.
> +     You'll need to create a local fork of your public GIT repository.  You can
> +     do this by:
> +
> +	git clone ssh://%REMOTE_BOX/my/git/trees/%MY_DIR %DEVEL_DIR
> +
> +     This will create a checked-out GIT tree in a directory (%DEVEL_DIR) that
> +     you can later use for development.  If you have a local mirror of the
> +     upstream tree that you're using as a base, you can tell git to use the
> +     objects from that to save space:
> +
> +	git clone --reference %LOCAL_UPSTREAM_MIRROR \
> +		ssh://%REMOTE_BOX/my/git/trees/%MY_DIR \
> +		%DEVEL_DIR
> +
> +     [!] NOTE: You must use ssh: and not git: to clone your tree because you
> +     	       need to be able to push back (write) to your public tree.
> +
> +     To continue my example, I have a local mirror of Linus's kernel, regularly
> +     updated by cron, and so to make my local NOMMU development tree, I would
> +     do:
> +
> +	git clone --reference /warthog/git/linux-2.6 \
> +		ssh://master.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-2.6-nommu.git \
> +		linux-2.6-nommu
> +
> +
> + (4) Now you need to set up your local GIT tree to make it possible (a) update
> +     your development tree by pulling in the upstream tree, and (b) publish
> +     your changes by pushing them to your public tree.
> +
> +	cd %DEVEL_DIR
> +
> +     Tell your repository where to find the upstream tree:
> +
> +	git remote add %UPSTREAM %UPSTREAM_REPO
> +
> +     where %UPSTREAM is the name you by which you want to refer to the upstream
> +     repository to git pull.  For Linus's upstream kernel, you might wish to
> +     use 'linus' for example.
> +
> +     In my example, I did the following to pull Linus's tree into branches of
> +     my tree:
> +
> +	cd linux-2.6-nommu
> +	git remote add linus \
> +		git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
> +
> +     Looking in .git/config, I now see section that looks like this:
> +
> +	[remote "origin"]
> +		url = ssh://master.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-2.6-nommu.git
> +		fetch = +refs/heads/*:refs/remotes/origin/*
> +	[branch "master"]
> +		remote = origin
> +		merge = refs/heads/master
> +	[remote "linus"]
> +		url = git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
> +		fetch = +refs/heads/*:refs/remotes/linus/*
> +
> +
> + (5) You should now be able to update your development tree from the upstream
> +     repository to make sure that works:
> +
> +	git fetch -v %UPSTREAM
> +
> +     In my case, that's:
> +
> +	git fetch -v linus
> +
> +     If you've just created the repository, it'll probably just say that things
> +     are up to date:
> +
> +	From git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6
> +	 = [up to date]      master     -> linus/master
> +
> +     [!] NOTE: I cannot determine a way of making "git pull linus" work without
> +     	 setting branch.master.remote to 'linus'.
> +
> +
> + (6) And then you should be able to publish your development tree by pushing it
> +     to your public tree, thus allowing the rest of the world to see your
> +     changes.
> +
> +	git push -v origin
> +
> +
> + (7) Finally you should be able to pull your published tree back into your
> +     development tree, and it should just say that it's up to date:
> +
> +	git pull -v
> +
> +
> +UPDATING YOUR DEVELOPMENT TREE
> +------------------------------
> +
> +Okay: so you've got your tree, and you've made changes to it, and now Linus has
> +gone and dumped five thousand patches into his tree, making the base for your
> +changes obsolete.  You need to update your tree and fix up your changes.
> +
> +If you haven't yet committed your changes, you'll have to siphon them off into
> +a file:
> +
> +	git diff >a.diff
> +
> +and deapply them:
> +
> +	patch -p1 -R <a.diff
> +
> +You can then update your tree from the upstream tree with no fear of a conflict
> +(assuming you don't also have changes that you have committed).  Once you've
> +updated your tree, you can reapply your changes:
> +
> +	patch -p1 <a.diff
> +
> +And then fix up the rejects with your favourite editor and a few choice curses.
> +
> +
> +To actually update your tree, you can do the following:
> +
> +	git fetch %UPSTREAM
> +
> +In my example, that'd be:
> +
> +	git fetch linus
> +
> +If you have committed changes, this will attempt to merge them, but you may
> +still need to fix them up.  If everything went smoothly this will automatically
> +commit a merge on top of the tree and set the HEAD pointer to that.  This merge
> +will point at your last tree and the tree you just merged from upstream, and
> +will indicate that the resulting tree is a combination of both.  Of course, you
> +shouldn't assume it will still compile, let alone still work...
> +
> +If you do need to fix them up, refer to the "Manually merging failed fetches"
> +section for guidance.
> +
> +You can view the merge that git pull committed by:
> +
> +	git show
> +
> +And you can view the tree structure at that point with the gitk command.
> +
> +
> +PUBLISHING YOUR CHANGES
> +-----------------------
> +
> +Finally, you're in a position to make your changes available.  Firstly, you
> +have to commit them to your development tree (as mentioned previously) and then
> +you have to make them available to the rest of the world.  To do that, simply
> +run:
> +
> +	git push
> +
> +which will apply the changes to your public tree.  If you have web access to
> +your git tree, these will eventually become visible through there.
> +
> +You may then have to tell your upstream maintainer what you'd like them to pull
> +from your tree.  The standard way to do this is to do:
> +
> +	git request-pull %BASE_ID %MY_REPO >/tmp/request.txt
> +
> +where %BASE_ID is the head of the tree on which your changes are based, and
> +%MY_REPO is the public URL of your repository.  If you have your development
> +git tree configured to know where the upstream remote repository is, then if
> +you've ever done 'git fetch' you should have a branch for it, named something
> +like "%UPSTREAM/%UPSTREAM_BRANCH" where %UPSTREAM is the name you gave to 'git
> +remote' and %UPSTREAM_BRANCH is the upstream branch on which you've based your
> +development (almost certainly 'master').
> +
> +This command will generate a list of all the patches between %BASE_ID and the
> +head of your tree that you are asking to be pulled.
> +
> +In my example, I can do:
> +
> +	git request-pull linus/master \
> +		git://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-2.6-nommu.git \
> +		>/tmp/request.txt
> +
> +You should then edit /tmp/request.txt to include a description of what you're
> +trying to achieve with these patches, and then mail the whole file to the
> +upstream maintainer.
> +
> +[!] NOTE: It may take some time for the git push to take full effect.  Before
> +    that time is up, git request-pull may give spurious warnings and the test
> +    it produces may say that the branch is unverified.
> +
> +
> +===============================
> +MANUALLY MERGING FAILED FETCHES
> +===============================
> +
> +Occasionally, when you pull someone else's tree in to your repository, either
> +because the base needs updating or because you're incorporating stuff from a
> +contributor, the merge will fail due to conflicts between the changes you have
> +made in your tree, and the changes you're importing.
> +
> +GIT will try and automatically merge where possible, but it can't always manage
> +it.  In such cases you have to unlimber your text editor and fix it manually.
> +
> +GIT will report the files that need merging during the git fetch/git pull:
> +
> +	CONFLICT (content): Merge conflict in drivers/char/tty_audit.c
> +
> +and they can also be determined by looking in ".git/MERGE_MSG".
> +
> +GIT will interpolate markers into the affected files, along with both versions
> +of the code:
> +
> +	<<<<<<< HEAD:drivers/char/tty_audit.c
> +					 tsk->pid, uid, loginuid, sessionid,
> +	=======
> +					 tsk->pid, tsk->uid, loginuid, sessionid,
> +	>>>>>>> b3985e2bf6ce51ae943208af4bd336287fb34ed6:drivers/char/tty_audit.c
> +
> +The first section (<<<<<<<< to =======) is the version from your tree, the
> +second section (======= to >>>>>>>) is the version from the tree being
> +imported.  The markers must be removed, and the conflicting code resolved down
> +to the appropriate final version.
> +
> +
> +Once that is done, git add (or git rm) must be called on the changed files so
> +that git commit knows to include them in the new head.  It works exactly like
> +changing files normally (as per the "Making changes" section), except that GIT
> +has stored extra data that will go into the merge commit when git commit
> +creates it.
> +
> +
> +=============
> +LOCATING BUGS
> +=============
> +
> +There will be times when the program you've built malfunctions.  It happens now
> +and then even to the best of projects.  Sometimes you can easily locate the bug
> +by looking at the symptoms and the debugging output and then eyeballing the
> +code, and sometimes you can't.
> +
> +For very big projects such as the Linux kernel, finding a bug that someone else
> +has inadvertently introduced can be very hard, but GIT allows you to take
> +advantage of the fact that the changes are introduced a bit at a time with
> +clear boundaries (commits) to make life a bit easier.
> +
> +
> +BISECTION
> +---------
> +
> +What you really want to be able to do is to isolate the commit that's causing
> +the malfunction, but with automation support so that you don't have to trace
> +the commit tree yourself.  GIT has a tool to do this: git bisect.
> +
> +The way this works is to take two points in the tree: one at which you know the
> +program malfunctions, and one at which you know it doesn't, and then chop its
> +way through the tree to locate the failing commit.
> +
> +To illustrate this:
> +
> + (1) Assume that you're dealing with the kernel, and that you find that after
> +     Linus's merge window, 2.6.25-rc1 does not boot for you, but you know that
> +     2.6.24 did prior to the window.
> +
> +     Firstly you have to start your search and describe the bounds (the working
> +     and non-working points).  This is done with the following commands:
> +
> +	git bisect start [%BAD_COMMIT [%GOOD_COMMIT]]
> +	git bisect bad [%BAD_COMMIT]
> +	git bisect good [%GOOD_COMMIT]
> +
> +     where %BAD_COMMIT and %GOOD_COMMIT are optional commit object IDs or
> +     symbolic representations thereof.  The 'bad' command is unnecessary if
> +     %BAD_COMMIT is given to 'start', and the 'good' command is not required if
> +     %GOOD_COMMIT is given to 'start'.
> +
> +     So, in the example we're looking at, you could do:
> +
> +	git bisect start
> +	git bisect bad v2.6.25-rc1
> +	git bisect good v2.6.24
> +
> +     or:
> +
> +	git bisect start v2.6.25-rc1
> +	git bisect good v2.6.24
> +
> +     or:
> +
> +	git bisect start v2.6.25-rc1 v2.6.24
> +
> +	[!] NOTE: This is using a symbolic tag 'v2.6.24' to refer to the last
> +     	    commit before 2.6.24 was declared.
> +
> +
> +     However, if 2.6.25-rc1 is at currently at the head of your tree, you can
> +     do:
> +
> +	git bisect start
> +	git bisect bad
> +
> +     to indicate that this malfunctioned, or you could do this in a single
> +     command:
> +
> +	git bisect start HEAD
> +
> +     to start bisection _and_ indicate that the HEAD revision is bad.
> +
> +
> +     Alternatively, if you're at a point where the program _does_ work, you can
> +     pass either HEAD or no parameter to the 'good' bisection command, or pass
> +     HEAD as the %GOOD_COMMIT parameter to the 'start' bisection command.
> +
> +
> + (2) Now GIT will rumble through the commits between the two points you have
> +     declared, and set the current HEAD of the repository to a point that
> +     approximates midway between the two:
> +
> +	warthog>git bisect start v2.6.25-rc1 v2.6.24
> +	Bisecting: 4814 revisions left to test after this
> +	[d2e626f45cc450c00f5f98a89b8b4c4ac3c9bf5f] x86: add PAGE_KERNEL_EXEC_NOCACHE
> +
> +     and then it will check out the sources to reflect their state at this point.
> +
> +
> + (3) You should now attempt to compile this and test it.  If the test succeeds,
> +     you should run the command:
> +
> +	git bisect good
> +
> +     If the test fails, run the command:
> +
> +	git bisect bad
> +
> +     These will tell GIT to binary chop the commits between either the current
> +     point and the good end or the current point and the bad end to find a new
> +     commit to test:
> +
> +	warthog>git bisect bad
> +	Bisecting: 2406 revisions left to test after this
> +	[fb46990dba94866462e90623e183d02ec591cf8f] [NETFILTER]: nf_queue: remove unnecessary hook existance check
> +	warthog>git bisect good
> +	Bisecting: 1203 revisions left to test after this
> +	[936722922f6d2366378de606a40c14f96915474d] [IPV4] fib_trie: compute size when needed
> +
> +     As for when bisection started, GIT will set the current HEAD pointer and
> +     then check out the sources.  You should repeat step (3).
> +
> +     If the commit is broken for you and the compile fails, run the command:
> +
> +	git bisect skip
> +
> +     this will cause the bisection algorithm to move onto the next commit in
> +     the hope that this one will be better:
> +
> +	warthog>git bisect skip
> +	Bisecting: 1203 revisions left to test after this
> +	[1328042e268c936189f15eba5bd9a5a4605a8581] [IPV4] fib_trie: use hash list
> +
> +     this will change the HEAD pointer and check out the sources.  Repeat step
> +     (3).
> +
> +
> + (4) Eventually, after you've tested a number of different commits, GIT will
> +     tell you that it has narrowed the problem down to either a single commit,
> +     or if there were compile errors that got in the way, a range of commits:
> +
> +	warthog>git bisect bad
> +	e3ac5298159c5286cef86f0865d4fa6a606bd391 is first bad commit
> +	commit e3ac5298159c5286cef86f0865d4fa6a606bd391
> +	Author: Patrick McHardy <kaber@trash.net>
> +	Date:   Wed Dec 5 01:23:57 2007 -0800
> +
> +	    [NETFILTER]: nf_queue: make queue_handler const
> +
> +	    Signed-off-by: Patrick McHardy <kaber@trash.net>
> +	    Signed-off-by: David S. Miller <davem@davemloft.net>
> +	...
> +
> +
> + (5) At any time during the bisection process, you can use:
> +
> +	git show
> +
> +     to examine the commit currently selected for testing, and:
> +
> +	git bisect log
> +
> +     to view the log of information provided by you through git bisect start,
> +     good and bad, and:
> +
> +	git bisect visualize
> +
> +     to start up the gitk program to show you a graphical view of the current
> +     good-to-bad range of commits as narrowed down by bisection.
> +
> +
> + (6) You should then end the bisection process by:
> +
> +	git bisect reset
> +
> +
> +BLAME
> +-----
> +
> +Now imagine that rather than indulging in bisection you've found a bug by
> +simply looking at the code: who do you tell about it?  You could look at the
> +banner comment at the top of the file to look for names and email addresses,
> +and you could also look in the kernel MAINTAINERS file or its equivalent, but
> +the person you really want to harangue is whoever made the change...
> +
> +There's a very useful GIT tool to help determine this:
> +
> +	git blame <file>
> +
> +also known as:
> +
> +	git annotate <file>
> +
> +which will give you a list of lines in a source file against who changed them
> +last and in what commit.  You may find that your favourite editor has a
> +facility to run this for you (Emacs has vc-annotate, bound to C-x v g, for
> +example).
> +
> +Running git blame on the kernel's README file, for example, might show:
> +
> +	warthog>git blame README
> +	620034c8 (Jesper Juhl                    2006-12-07 00:45:58 +0100   1)         Linux kernel release 2.6.xx <http://kernel.org/>
> +	^1da177e (Linus Torvalds                 2005-04-16 15:20:36 -0700   2)
> +	^1da177e (Linus Torvalds                 2005-04-16 15:20:36 -0700   3) These are the release notes for Linux version 2.6.  Read them carefully,
> +	...
> +
> +The hex number that occurs first on the line is a truncated commit object ID,
> +and this can be passed to git-show (remove the '^' symbol first, if given).
> +
> +	warthog>git show 1da177e
> +	commit 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2
> +	Author: Linus Torvalds <torvalds@ppc970.osdl.org>
> +	Date:   Sat Apr 16 15:20:36 2005 -0700
> +	...
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/

Re: [PATCH] Simplified GIT usage guide

[J. Bruce Fields]

On Fri, Dec 12, 2008 at 02:47:03PM -0500, bfields wrote:
> On Fri, Dec 12, 2008 at 06:28:27PM +0000, David Howells wrote:
> > Add a guide to using GIT's simpler features.
> > 
> > Signed-off-by: David Howells <dhowells@redhat.com>
> 
> Just a couple random thoughts:

(Also: this patch applies to either the git or linux trees, and you sent
it to both mailing lists.  Looks like you meant it for linux, but you
might want to clarify....)

--b.

> 
> 	- The advantage of adding this to the kernel tree is that you
> 	  can tailor it for a more specific audience (kernel developers
> 	  and testers).  A lot of this (e.g. the object-database
> 	  discussion) seems to be generic introduction-to-git stuff.
> 	  Is there some canonical external documentation you could refer
> 	  to for that stuff, that would allow you to get more quickly to
> 	  the more tailored information?  If not, is there something you
> 	  could improve to the point where you *would* be comfortable
> 	  referring to it?
> 	- How much overlap is there with
> 	  Documentation/development-process/7.AdvancedTopics?  Should
> 	  there be cross-references between the two?
> 
> There's an awful lot of introductions to git out there now (and I've got
> my own share of the blame).

Re: [PATCH] Simplified GIT usage guide

[David Howells]

J. Bruce Fields <bfields@fieldses.org> wrote:

> (Also: this patch applies to either the git or linux trees, and you sent
> it to both mailing lists.  Looks like you meant it for linux, but you
> might want to clarify....)

It was aimed at addition to Linux, but someone might think it goes better in
GIT instead, and the GIT list is more narrowly focused on the right people to
review it.

David

Re: [PATCH] Simplified GIT usage guide

[Jeff Garzik]

David Howells wrote:
> Add a guide to using GIT's simpler features.
> 
> Signed-off-by: David Howells <dhowells@redhat.com>
> ---
> 
>  Documentation/git-haters-guide.txt | 1283 ++++++++++++++++++++++++++++++++++++
>  1 files changed, 1283 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/git-haters-guide.txt

What do you feel is missing from the Kernel Hackers' Guide to Git?  :)

http://linux.yyz.us/git-howto.html

	Jeff

Re: [PATCH] Simplified GIT usage guide

[Chris Friesen]

Jeff Garzik wrote:

> What do you feel is missing from the Kernel Hackers' Guide to Git?  :)
> 
> http://linux.yyz.us/git-howto.html

This is useful.  I also keep a bookmark to the Git User's Manual:

http://www.kernel.org/pub/software/scm/git/docs/user-manual.html

Chris

Re: [PATCH] Simplified GIT usage guide

[Junio C Hamano]

Jeff Garzik <jeff@garzik.org> writes:

> What do you feel is missing from the Kernel Hackers' Guide to Git?  :)
>
> http://linux.yyz.us/git-howto.html
>
> 	Jeff

For a starter, it is not in-tree ;-).

Re: [PATCH] Simplified GIT usage guide

[Nick Andrew]

On Fri, Dec 12, 2008 at 03:00:17PM -0500, Jeff Garzik wrote:
> David Howells wrote:
>> Add a guide to using GIT's simpler features.
>>
>> Signed-off-by: David Howells <dhowells@redhat.com>
>> ---
>>
>>  Documentation/git-haters-guide.txt | 1283 ++++++++++++++++++++++++++++++++++++
>>  1 files changed, 1283 insertions(+), 0 deletions(-)
>>  create mode 100644 Documentation/git-haters-guide.txt
>
> What do you feel is missing from the Kernel Hackers' Guide to Git?  :)
>
> http://linux.yyz.us/git-howto.html

Better advertising, for one :-)

And how to work with different trees in the same local repo.

Nick.

Re: [PATCH] Simplified GIT usage guide

[Nicolas Pitre]

Another obvious correction...

On Fri, 12 Dec 2008, David Howells wrote:

> +     A commit object will typically refer to one base commit when someone has
> +     merely committed some changes on top of the current state, and two base
> +     commits when a couple of trees have been merged.

If you have two bases, then only two trees were merged together.  If you 
merged a "couple" of trees, then a "couple" of bases are registered.


Nicolas

Re: [PATCH] Simplified GIT usage guide

[David Howells]

Jeff Garzik <jeff@garzik.org> wrote:

> What do you feel is missing from the Kernel Hackers' Guide to Git?  :)

Quite a lot.  Most notably the section I have on publishing changes by GIT
tree.  It's taken a lot of experimentation to work out how to do it, and I'm
sure it can be done better.  I hadn't managed to find anywhere on the web
describing how to do it that I could follow, and no-one that I asked was really
willing to help me set it up.

I have a number of crib sheets that I've cobbled together to note how to do
things that I can cut and paste from, so I turned them into a document.

David

Re: [PATCH] Simplified GIT usage guide

[David Howells]

Jakub Narebski <jnareb@gmail.com> wrote:

> Wouldn't it be better to update either "Git User's Manual",

This is better in some ways than book.git-scm.com.  It has pictures for one
thing.  It does, however, go into too much detail too quickly.

> or http://book.git-scm.com?

I didn't see that when googling for stuff.  I have four issues with what's on
this website, though I could perhaps, as you point out, fix three of them
myself:

 (1) It really needs a pictorial representation of the virtual GIT tree.  How
     GIT actually stores its data is irrelevant to people trying to use GIT
     rather than trying to modify GIT.  It would help those trying to use GIT
     if you can help them visualise what they're dealing with.  It doesn't
     have to be complex.

     See the attached FIG file for examples.  Try running it through:

	fig2dev -L pdf <in.fig >out.pdf

 (2) In my document I've tried to thread a worked example through, so that if
     you go through all the steps, they'll work in order.  I'm not sure I've
     been entirely successful, though.

 (3) You put some non-basic stuff in the basic section (branching - this isn't
     ordinarily useful, IMHO), but you miss other stuff out ('git rm' for
     example).

 (4) It needs to be installed with GIT in a form that can easily be cut and
     pasted from (maybe this is the case).

I like the videos, though not all of them work, and a number of sections say
things like:

	github
	repoorcz

whatever that means.

David

#FIG 3.2
Landscape
Center
Inches
A4
100.00
Single
-2
1200 2
0 32 #efefef
0 33 #7f7f7f
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 15420 1485 15660 2025 15660 2025 15420 1485 15420
4 1 0 49 -1 0 10 0.000 4 2 540 1755 15600 C0\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 14820 4365 15060 4905 15060 4905 14820 4365 14820
4 1 0 49 -1 0 10 0.000 4 2 540 4635 15000 B1\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 14820 1485 15060 2025 15060 2025 14820 1485 14820
4 1 0 49 -1 0 10 0.000 4 2 540 1755 15000 C1\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 14220 4365 14460 4905 14460 4905 14220 4365 14220
4 1 0 49 -1 0 10 0.000 4 2 540 4635 14400 B2\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 14220 1485 14460 2025 14460 2025 14220 1485 14220
4 1 0 49 -1 0 10 0.000 4 2 540 1755 14400 C2\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 13620 4365 13860 4905 13860 4905 13620 4365 13620
4 1 0 49 -1 0 10 0.000 4 2 540 4635 13800 B3\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 13620 1485 13860 2025 13860 2025 13620 1485 13620
4 1 0 49 -1 0 10 0.000 4 2 540 1755 13800 C3\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 13020 1485 13260 2025 13260 2025 13020 1485 13020
4 1 0 49 -1 0 10 0.000 4 2 540 1755 13200 C4\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 12300 1485 12540 2025 12540 2025 12300 1485 12300
4 1 0 49 -1 0 10 0.000 4 2 540 1755 12480 C0\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 11700 4365 11940 4905 11940 4905 11700 4365 11700
4 1 0 49 -1 0 10 0.000 4 2 540 4635 11880 B1\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 11700 1485 11940 2025 11940 2025 11700 1485 11700
4 1 0 49 -1 0 10 0.000 4 2 540 1755 11880 C1\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 11100 4365 11340 4905 11340 4905 11100 4365 11100
4 1 0 49 -1 0 10 0.000 4 2 540 4635 11280 B2\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 11100 1485 11340 2025 11340 2025 11100 1485 11100
4 1 0 49 -1 0 10 0.000 4 2 540 1755 11280 C2\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 10500 4365 10740 4905 10740 4905 10500 4365 10500
4 1 0 49 -1 0 10 0.000 4 2 540 4635 10680 B3\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 10500 1485 10740 2025 10740 2025 10500 1485 10500
4 1 0 49 -1 0 10 0.000 4 2 540 1755 10680 C3\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 9780 4365 10020 4905 10020 4905 9780 4365 9780
4 1 0 49 -1 0 10 0.000 4 2 540 4635 9960 F1A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 9300 4365 9540 4905 9540 4905 9300 4365 9300
4 1 0 49 -1 0 10 0.000 4 2 540 4635 9480 F2A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 2835 9300 2835 9540 3375 9540 3375 9300 2835 9300
4 1 0 49 -1 0 10 0.000 4 2 540 3105 9480 D0\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 9300 1485 9540 2025 9540 2025 9300 1485 9300
4 1 0 49 -1 0 10 0.000 4 2 540 1755 9480 C0\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 8820 4365 9060 4905 9060 4905 8820 4365 8820
4 1 0 49 -1 0 10 0.000 4 2 540 4635 9000 F3A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 2835 8340 2835 8580 3375 8580 3375 8340 2835 8340
4 1 0 49 -1 0 10 0.000 4 2 540 3105 8520 D1\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 8340 1485 8580 2025 8580 2025 8340 1485 8340
4 1 0 49 -1 0 10 0.000 4 2 540 1755 8520 C1\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 8100 4365 8340 4905 8340 4905 8100 4365 8100
4 1 0 49 -1 0 10 0.000 4 2 540 4635 8280 F2B\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 7620 1485 7860 2025 7860 2025 7620 1485 7620
4 1 0 49 -1 0 10 0.000 4 2 540 1755 7800 C3\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 6900 4365 7140 4905 7140 4905 6900 4365 6900
4 1 0 49 -1 0 10 0.000 4 2 540 4635 7080 F1A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 6420 4365 6660 4905 6660 4905 6420 4365 6420
4 1 0 49 -1 0 10 0.000 4 2 540 4635 6600 F2A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 2835 6420 2835 6660 3375 6660 3375 6420 2835 6420
4 1 0 49 -1 0 10 0.000 4 2 540 3105 6600 D0\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 6420 1485 6660 2025 6660 2025 6420 1485 6420
4 1 0 49 -1 0 10 0.000 4 2 540 1755 6600 C0\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 5940 4365 6180 4905 6180 4905 5940 4365 5940
4 1 0 49 -1 0 10 0.000 4 2 540 4635 6120 F3A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 2835 5460 2835 5700 3375 5700 3375 5460 2835 5460
4 1 0 49 -1 0 10 0.000 4 2 540 3105 5640 D1\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 5460 1485 5700 2025 5700 2025 5460 1485 5460
4 1 0 49 -1 0 10 0.000 4 2 540 1755 5640 C1\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 5220 4365 5460 4905 5460 4905 5220 4365 5220
4 1 0 49 -1 0 10 0.000 4 2 540 4635 5400 F2B\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 2835 4740 2835 4980 3375 4980 3375 4740 2835 4740
4 1 0 49 -1 0 10 0.000 4 2 540 3105 4920 D2\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 4740 1485 4980 2025 4980 2025 4740 1485 4740
4 1 0 49 -1 0 10 0.000 4 2 540 1755 4920 C2\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 4500 4365 4740 4905 4740 4905 4500 4365 4500
4 1 0 49 -1 0 10 0.000 4 2 540 4635 4680 F1B\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 3780 4365 4020 4905 4020 4905 3780 4365 3780
4 1 0 49 -1 0 10 0.000 4 2 540 4635 3960 F1A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 3300 4365 3540 4905 3540 4905 3300 4365 3300
4 1 0 49 -1 0 10 0.000 4 2 540 4635 3480 F2A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 2835 3300 2835 3540 3375 3540 3375 3300 2835 3300
4 1 0 49 -1 0 10 0.000 4 2 540 3105 3480 D0\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 3300 1485 3540 2025 3540 2025 3300 1485 3300
4 1 0 49 -1 0 10 0.000 4 2 540 1755 3480 C0\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 2820 4365 3060 4905 3060 4905 2820 4365 2820
4 1 0 49 -1 0 10 0.000 4 2 540 4635 3000 F3A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 2835 2340 2835 2580 3375 2580 3375 2340 2835 2340
4 1 0 49 -1 0 10 0.000 4 2 540 3105 2520 D1\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 2340 1485 2580 2025 2580 2025 2340 1485 2340
4 1 0 49 -1 0 10 0.000 4 2 540 1755 2520 C1\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 2100 4365 2340 4905 2340 4905 2100 4365 2100
4 1 0 49 -1 0 10 0.000 4 2 540 4635 2280 F2B\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 1260 4365 1500 4905 1500 4905 1260 4365 1260
4 1 0 49 -1 0 10 0.000 4 2 540 4635 1440 F1A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 780 4365 1020 4905 1020 4905 780 4365 780
4 1 0 49 -1 0 10 0.000 4 2 540 4635 960 F2A\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 2835 780 2835 1020 3375 1020 3375 780 2835 780
4 1 0 49 -1 0 10 0.000 4 2 540 3105 960 D0\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 1485 780 1485 1020 2025 1020 2025 780 1485 780
4 1 0 49 -1 0 10 0.000 4 2 540 1755 960 C0\001
2 2 0 1 0 7 50 -1 19 0.000 0 0 -1 0 0 5
	 4365 300 4365 540 4905 540 4905 300 4365 300
4 1 0 49 -1 0 10 0.000 4 2 540 4635 480 F3A\001
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 15420 1755 15060
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 2025 14940 4365 14940
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 4635 14820 4635 14460
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 14820 1755 14460
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 4635 14220 4635 13860
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 14220 1755 13860
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 4365 13740 3555 13740
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 13620 1755 13260
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 3
	1 1 0.00 60.000 120.000
	 4635 13620 4635 13140 2025 13140
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1485 13140 675 13140
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 12300 1755 11940
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 2025 11820 4365 11820
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 4635 11700 4635 11340
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 11700 1755 11340
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 4635 11100 4635 10740
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 11100 1755 10740
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 4365 10620 3555 10620
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1485 10620 675 10620
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 2835 9420 2025 9420
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 4
	1 1 0.00 60.000 120.000
	 4365 9900 4005 9900 4005 9420 3375 9420
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 3
	1 1 0.00 60.000 120.000
	 4005 9420 4005 9060 4365 9060
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
	1 1 0.00 60.000 120.000
	 4005 9420 4365 9420
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 9300 1755 8580
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 2835 8460 2025 8460
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 1 4
	1 1 0.00 60.000 120.000
	1 1 0.00 60.000 120.000
	 4365 9780 3825 9780 3825 8940 4365 8940
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 3
	1 1 0.00 60.000 120.000
	 3825 8460 3825 8220 4365 8220
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
	 3825 8940 3825 8460 3375 8460
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 8340 1755 7860
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 4
	1 1 0.00 60.000 120.000
	 2835 9300 2385 9300 2385 7740 2025 7740
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1485 7740 675 7740
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 2835 6540 2025 6540
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 4
	1 1 0.00 60.000 120.000
	 4365 7020 4005 7020 4005 6540 3375 6540
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 3
	1 1 0.00 60.000 120.000
	 4005 6540 4005 6180 4365 6180
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
	1 1 0.00 60.000 120.000
	 4005 6540 4365 6540
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 6420 1755 5700
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 2835 5580 2025 5580
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 1 4
	1 1 0.00 60.000 120.000
	1 1 0.00 60.000 120.000
	 4365 6900 3825 6900 3825 6060 4365 6060
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 3
	1 1 0.00 60.000 120.000
	 3825 5580 3825 5340 4365 5340
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
	 3825 6060 3825 5580 3375 5580
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 5460 1755 4980
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 2835 4860 2025 4860
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1485 4860 675 4860
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 1 4
	1 1 0.00 60.000 120.000
	1 1 0.00 60.000 120.000
	 4365 5940 3645 5940 3645 5220 4365 5220
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 3
	1 1 0.00 60.000 120.000
	 3645 4860 3645 4620 4365 4620
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
	 3645 5220 3645 4860 3375 4860
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 2835 3420 2025 3420
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 4
	1 1 0.00 60.000 120.000
	 4365 3900 4005 3900 4005 3420 3375 3420
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 3
	1 1 0.00 60.000 120.000
	 4005 3420 4005 3060 4365 3060
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
	1 1 0.00 60.000 120.000
	 4005 3420 4365 3420
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1755 3300 1755 2580
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 2835 2460 2025 2460
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1485 2460 675 2460
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 1 4
	1 1 0.00 60.000 120.000
	1 1 0.00 60.000 120.000
	 4365 3780 3825 3780 3825 2940 4365 2940
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 3
	1 1 0.00 60.000 120.000
	 3825 2460 3825 2220 4365 2220
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
	 3825 2940 3825 2460 3375 2460
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 2835 900 2025 900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 2
	1 1 0.00 60.000 120.000
	 1485 900 675 900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 1 4
	1 1 0.00 60.000 120.000
	 4365 1380 4005 1380 4005 900 3375 900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 3
	1 1 0.00 60.000 120.000
	 4005 900 4005 420 4365 420
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
	1 1 0.00 60.000 120.000
	 4005 900 4365 900
4 0 0 49 -1 0 10 0.000 4 120 540 3600 13680 Branch\001
4 0 0 49 -1 0 10 0.000 4 120 360 720 13080 HEAD\001
4 0 0 49 -1 0 10 0.000 4 120 990 0 12840 POST-MERGE:\001
4 0 0 49 -1 0 10 0.000 4 120 540 3600 10560 Branch\001
4 0 0 49 -1 0 10 0.000 4 120 360 720 10560 HEAD\001
4 0 0 49 -1 0 10 0.000 4 120 900 0 10320 PRE-MERGE:\001
4 0 0 49 -1 0 10 0.000 4 120 360 720 7680 HEAD\001
4 0 0 49 -1 0 10 0.000 4 120 1350 0 7440 REVERT FILE F2:\001
4 0 0 49 -1 0 10 0.000 4 120 360 720 4800 HEAD\001
4 0 0 49 -1 0 10 0.000 4 120 1350 0 4320 CHANGE FILE F1:\001
4 0 0 49 -1 0 10 0.000 4 120 360 720 2400 HEAD\001
4 0 0 49 -1 0 10 0.000 4 120 1350 0 1920 CHANGE FILE F2:\001
4 0 0 49 -1 0 10 0.000 4 120 360 720 840 HEAD\001
4 0 0 49 -1 0 10 0.000 4 120 1170 0 120 INITIAL TREE:\001

Re: [PATCH] Simplified GIT usage guide

[Sverre Rabbelier]

On Sat, Dec 13, 2008 at 02:04, David Howells <dhowells@redhat.com> wrote:
>  (3) You put some non-basic stuff in the basic section (branching - this isn't
>     ordinarily useful, IMHO), but you miss other stuff out ('git rm' for
>     example).

Erm, branching is not ordinarily useful? I think you're Doing It Wrong
(TM) then, since branching is a Big Thing (also TM) in DVC, not using
branches would be a bit like only using the first 4 gears in a car;
sure, it's possible, but you're missing all that extra power!

>  (4) It needs to be installed with GIT in a form that can easily be cut and
>     pasted from (maybe this is the case).

I'll agree with you that the git-scm site is in fact, a site, and as
such cannot easily be accessed.

>        github

First hit on google:http://github.com/

>        repoorcz

http://repo.or.cz

I'm sure both are supposed to be hyperlinks, and some text there as well.

-- 
Cheers,

Sverre Rabbelier

Re: [PATCH] Simplified GIT usage guide

[Willy Tarreau]

On Sat, Dec 13, 2008 at 02:16:34AM +0100, Sverre Rabbelier wrote:
> On Sat, Dec 13, 2008 at 02:04, David Howells <dhowells@redhat.com> wrote:
> >  (3) You put some non-basic stuff in the basic section (branching - this isn't
> >     ordinarily useful, IMHO), but you miss other stuff out ('git rm' for
> >     example).
> 
> Erm, branching is not ordinarily useful? I think you're Doing It Wrong
> (TM) then, since branching is a Big Thing (also TM) in DVC, not using
> branches would be a bit like only using the first 4 gears in a car;
> sure, it's possible, but you're missing all that extra power!

People who want to use it as a CVS replacement don't realize that they're
using branches. They work in their local "master" branch, and don't realize
that when they fetch updates, they fetch them into a different branch.

CVS people are afraid of branches, so trying to explain them how they can
do what they're used to is better than telling them they'll have to do
what they're afraid of.

I found David's howto quite understandable. I've taught Git to people who
only knew about SVN and to people who had never heard about any SCM at all. I
tried to use the same approach each time, and while I noticed that explaining
how Git works and why it works like that appeared obvious to the newbies,
it was very awkward with SVN users. I switched to something more like
David's approach for those people and it helped a lot. They have plenty
of time after that to discover the tool by themselves.

I really think that David should maintain his doc after applying a few
fixes to it, just like Jeff maintains his own. Also, having several docs
out of the tree is better for a user looking for different analysis of
the tool than having everything offered as the product's documentation,
provided the links are easy to find (might be linked to from the Git doc).

Willy

Re: [PATCH] Simplified GIT usage guide

[Nicolas Pitre]

On Sat, 13 Dec 2008, David Howells wrote:

>  (3) You put some non-basic stuff in the basic section (branching - this isn't
>      ordinarily useful, IMHO), but you miss other stuff out ('git rm' for
>      example).

Hmmm... I use git branches many times a day, while I use git rm... 
well... almost never.


Nicolas

Re: [PATCH] Simplified GIT usage guide

[Junio C Hamano]

David Howells <dhowells@redhat.com> writes:

> Add a guide to using GIT's simpler features.
>
> Signed-off-by: David Howells <dhowells@redhat.com>
> ---
>
>  Documentation/git-haters-guide.txt | 1283 ++++++++++++++++++++++++++++++++++++
>  1 files changed, 1283 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/git-haters-guide.txt
>
>
> diff --git a/Documentation/git-haters-guide.txt b/Documentation/git-haters-guide.txt
> new file mode 100644
> index 0000000..51e4dac
> --- /dev/null
> +++ b/Documentation/git-haters-guide.txt
> @@ -0,0 +1,1283 @@
> +		      ===================================
> +		      THE GIT HATER'S GUIDE TO THE GALAXY
> +		      ===================================
> +
> +By David Howells <dhowells@redhat.com>
> +
> +Contents:
> ...
> +============
> +INTRODUCTION
> +============
> +
> +So, you want to do some Linux kernel development?  And you hear there's this
> +piece of software called 'GIT' that you probably ought to be using when dealing
> +with the kernel community?  Then you find out that not only was Linux started
> +by this Linus Torvalds person, but GIT was too!  Perhaps it doesn't seem fair:
> +Linus has not just _one_ huge piece of software named after himself, but _two_!
> +And on top of that, globe spanning hardware vendors just queue up to give him
> +all the herring he can eat!!
> +
> +Then you look at webpages about GIT.  You look at the manpages!  You run the
> +commands with --help!  And you *still* don't know how to do anything complex
> +with it!!  You feel certain that there's some secret rite you have to perform
> +to become a GIT initiate - probably something involving two goats, an altar and
> +a full moon - oh, and lots of beer (we *are* talking about kernel developers
> +after all).
> +
> +Then you ask around, and people look at you blankly, hedge or say that it's
> +easy and obvious (they should know - they wrote the damned thing).  You realise
> +that the manpages are more an aide-memoire and that what you really want is
> +some sort of crib sheet; something that can hold your hand whilst you cut and
> +paste things from of it until you can see the point.
> +
> +Well, let's see if I can help...
> +
> +
> +DISCLAIMER
> +----------
> +
> +I don't really know what I'm doing with GIT...

I think this patch is good up to this point.  It is mildly funny and there
would exist some people who share the same sense of humor as the above
paragraphs (I am unfortunately one of them, though).

I've only skimmed the remainder of the patch, and found there are quite a
few technical errors and deviations from standard terminologies that I do
not care to enumerate (I do not have infinite amount of time).  They make
me suspect that anybody who tries to learn from this document would be
harmed rather than helped in the longer run.

The document could be a good addition if the remainder of the patch is
replaced by a collection of links to better introductory documents that
are already available on the net, IMHO.

Re: [PATCH] Simplified GIT usage guide

[Matthieu Moy]

David Howells <dhowells@redhat.com> writes:

> +So, you want to do some Linux kernel development?  And you hear there's this
> +piece of software called 'GIT' that you probably ought to be using when dealing
> +with the kernel community?

I'm afraid too many people read this as "Git is only about kernel
hacking, if you're not a kernel hacker, find something else".

(and I think far too many people already think that indeed)

-- 
Matthieu

Re: [PATCH] Simplified GIT usage guide

[Marcin Slusarz]

On Fri, Dec 12, 2008 at 06:28:27PM +0000, David Howells wrote:
> +REVERTING COMMITTED CHANGES
> +---------------------------
> +
> +And sometimes you'll want to revert changes that you've committed, but that are
> +now buried beneath other commits.  Short of discarding and reapplying commits,
> +you have to apply a reverse patch:
> +
> +	git diff %COMMIT_ID | patch -p1 -R
> +
> +and then commit it.  Both the original application and the reversion will be
> +retained by GIT.

"git revert $commit" is a bit shorter.

Marcin

Re: [PATCH] Simplified GIT usage guide

[C. Scott Ananian]

On Fri, Dec 12, 2008 at 1:28 PM, David Howells <dhowells@redhat.com> wrote:
> Add a guide to using GIT's simpler features.
> diff --git a/Documentation/git-haters-guide.txt b/Documentation/git-haters-guide.txt
> +In the above example, I've assumed that you've got your own tree with the head
> +at commit C3, and that you've got a branch that you want to merge, which has
> +its head at commit B3.  After merging them, you'd end up with a directed,
> +cyclic tree:

That should be, "acyclic".  There are no cycles, because the graph is directed.
  --scott

-- 
                         ( http://cscott.net/ )

Re: [PATCH] Simplified GIT usage guide

[Michael J Gruber]

C. Scott Ananian venit, vidit, dixit 19.12.2008 01:47:
> On Fri, Dec 12, 2008 at 1:28 PM, David Howells <dhowells@redhat.com> wrote:
>> Add a guide to using GIT's simpler features.
>> diff --git a/Documentation/git-haters-guide.txt b/Documentation/git-haters-guide.txt
>> +In the above example, I've assumed that you've got your own tree with the head
>> +at commit C3, and that you've got a branch that you want to merge, which has
>> +its head at commit B3.  After merging them, you'd end up with a directed,
>> +cyclic tree:
> 
> That should be, "acyclic".  There are no cycles, because the graph is directed.

Well, directed graphs can have cycles. But the revision graph of a
revision control system has to be an acyclic directed graph. Otherwise
parenthood would be a complicated matter ;)

And no, trees by definition don't have cycles. Also, a "tree" in git
lingo is not the graph theoretic notion (which David uses, though
incorrectly); this only adds unnecessary points of confusion.

For whatever reason the graphs in version control systems are called
"dag"s, i.e. directed acyclic graphs, even though "acyclicity" depends
on whether you look at the directed or undirected graphs. (Branching
then merging gives an undirected cycle.) I guess one may read "directed"
as an attribute to "acyclic" here, i.e. ((directed acyclic) graph)
rather than (directed (acyclic graph)); so to say "directedly acyclic
graph". Or it's just that "dag" reads much better than "adg"...

So, please: Simplification yes, but not if it's unnecessarily misleading
or even plain wrong (referring to the original proposal, not the comment).

Cheers,
Michael

Re: [PATCH] Simplified GIT usage guide

[C. Scott Ananian]

On Fri, Dec 19, 2008 at 4:26 AM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> C. Scott Ananian venit, vidit, dixit 19.12.2008 01:47:
>> On Fri, Dec 12, 2008 at 1:28 PM, David Howells <dhowells@redhat.com> wrote:
>>> Add a guide to using GIT's simpler features.
>>> diff --git a/Documentation/git-haters-guide.txt b/Documentation/git-haters-guide.txt
>>> +In the above example, I've assumed that you've got your own tree with the head
>>> +at commit C3, and that you've got a branch that you want to merge, which has
>>> +its head at commit B3.  After merging them, you'd end up with a directed,
>>> +cyclic tree:
>>
>> That should be, "acyclic".  There are no cycles, because the graph is directed.
>
> Well, directed graphs can have cycles. But the revision graph of a
> revision control system has to be an acyclic directed graph. Otherwise
> parenthood would be a complicated matter ;)

I mean that the example given didn't have a cycle (even though it has
nodes arranged in a circle) because of the orientation of the edges.
But you're right, "directed acyclic graph" is a better correction; the
nodes in git do not form a tree.
 --scott

-- 
                         ( http://cscott.net/ )