![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index 8b5709ba75f328ad1e99c998ea50bc99791725c4..1c49e6995b42e42f1aba4e7b24d073e50c3b5234 100644 (file)
collection of interrelated snapshots (versions) of the project's
contents.
-A single git repository may contain multiple branches. Each branch
-is a bookmark referencing a particular point in the project history.
-The gitlink:git-branch[1] command shows you the list of branches:
+A single git repository may contain multiple branches. It keeps track
+of them by keeping a list of <<def_head,heads>> which reference the
+latest version on each branch; the gitlink:git-branch[1] command shows
+you the list of branch heads:
------------------------------------------------
$ git branch
* master
------------------------------------------------
-A freshly cloned repository contains a single branch, named "master",
-and the working directory contains the version of the project
-referred to by the master branch.
+A freshly cloned repository contains a single branch head, named
+"master", and working directory is initialized to the state of
+the project referred to by "master".
-Most projects also use tags. Tags, like branches, are references
-into the project's history, and can be listed using the
+Most projects also use <<def_tag,tags>>. Tags, like heads, are
+references into the project's history, and can be listed using the
gitlink:git-tag[1] command:
------------------------------------------------
------------------------------------------------
Tags are expected to always point at the same version of a project,
-while branches are expected to advance as development progresses.
+while heads are expected to advance as development progresses.
-Create a new branch pointing to one of these versions and check it
+Create a new branch head pointing to one of these versions and check it
out using gitlink:git-checkout[1]:
------------------------------------------------
$ git reset --hard v2.6.17
------------------------------------------------
-Note that if the current branch was your only reference to a
+Note that if the current branch head was your only reference to a
particular point in history, then resetting that branch may leave you
-with no way to find the history it used to point to; so use this
-command carefully.
+with no way to find the history it used to point to; so use this command
+carefully.
Understanding History: Commits
------------------------------
below. Commits are shown as "o", and the links between them with
lines drawn with - / and \. Time goes left to right:
+
+................................................
o--o--o <-- Branch A
/
o--o--o <-- master
\
o--o--o <-- Branch B
+................................................
If we need to talk about a particular commit, the character "o" may
be replaced with another letter or number.
Understanding history: What is a branch?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Though we've been using the word "branch" to mean a kind of reference
-to a particular commit, the word branch is also commonly used to
-refer to the line of commits leading up to that point. In the
-example above, git may think of the branch named "A" as just a
-pointer to one particular commit, but we may refer informally to the
-line of three commits leading up to that point as all being part of
+When we need to be precise, we will use the word "branch" to mean a line
+of development, and "branch head" (or just "head") to mean a reference
+to the most recent commit on a branch. In the example above, the branch
+head named "A" is a pointer to one particular commit, but we refer to
+the line of three commits leading up to that point as all being part of
"branch A".
-If we need to make it clear that we're just talking about the most
-recent commit on the branch, we may refer to that commit as the
-"head" of the branch.
+However, when no confusion will result, we often just use the term
+"branch" both for branches and for branch heads.
Manipulating branches
---------------------
branch--then you are warned; the output may look something like this:
-------------------------------------------------
-$ git pull . next
-Trying really trivial in-index merge...
-fatal: Merge requires file-level merging
-Nope.
-Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
-Merging:
-15e2162 world
-77976da goodbye
-found 1 common ancestor(s):
-d122ed4 initial
-Auto-merging file.txt
+$ git merge next
+ 100% (4/4) done
+Auto-merged file.txt
CONFLICT (content): Merge conflict in file.txt
Automatic merge failed; fix conflicts and then commit the result.
-------------------------------------------------
gitlink:git-show[1]:
-------------------------------------------------
-$ git show HEAD^ path/to/file
+$ git show HEAD^:path/to/file
-------------------------------------------------
which will display the given version of the file.
then you can just pull changes from each other's repositories
directly; note that all of the commands (gitlink:git-clone[1],
git-fetch[1], git-pull[1], etc.) that accept a URL as an argument
-will also accept a local file patch; so, for example, you can
+will also accept a local directory name; so, for example, you can
use
-------------------------------------------------
You have performed no merges into mywork, so it is just a simple linear
sequence of patches on top of "origin":
-
+................................................
o--o--o <-- origin
\
o--o--o <-- mywork
+................................................
Some more interesting work has been done in the upstream project, and
"origin" has advanced:
+................................................
o--o--O--o--o--o <-- origin
\
a--b--c <-- mywork
+................................................
At this point, you could use "pull" to merge your changes back in;
the result would create a new merge commit, like this:
-
+................................................
o--o--O--o--o--o <-- origin
\ \
a--b--c--m <-- mywork
+................................................
However, if you prefer to keep the history in mywork a simple series of
commits without any merges, you may instead choose to use
patches to the new mywork. The result will look like:
+................................................
o--o--O--o--o--o <-- origin
\
a'--b'--c' <-- mywork
+................................................
In the process, it may discover conflicts. In that case it will stop
and allow you to fix the conflicts; after fixing conflicts, use "git
with merging. Suppose somebody fetches your branch and merges it into
their branch, with a result something like this:
+................................................
o--o--O--o--o--o <-- origin
\ \
t--t--t--m <-- their branch:
+................................................
Then suppose you modify the last three commits:
+................................................
o--o--o <-- new head of origin
/
o--o--O--o--o--o <-- old head of origin
+................................................
If we examined all this history together in one repository, it will
look like:
+................................................
o--o--o <-- new head of origin
/
o--o--O--o--o--o <-- old head of origin
\ \
t--t--t--m <-- their branch:
+................................................
Git has no way of knowing that the new head is an updated version of
the old head; it treats this situation exactly the same as it would if
A fast forward looks something like this:
+................................................
o--o--o--o <-- old head of the branch
\
o--o--o <-- new head of the branch
+................................................
In some cases it is possible that the new head will *not* actually be
realized she made a serious mistake, and decided to backtrack,
resulting in a situation like:
+................................................
o--o--o--o--a--b <-- old head of the branch
\
o--o--o <-- new head of the branch
-
-
+................................................
In this case, "git fetch" will fail, and print out a warning.
$ git-merge-index git-merge-one-file hello.c
-------------------------------------------------
-and that is what higher level `git resolve` is implemented with.
+and that is what higher level `git merge -s resolve` is implemented with.
How git stores objects efficiently: pack files
----------------------------------------------
contrast, running "git prune" while somebody is actively changing the
repository is a *BAD* idea).
-Glossary of git terms
-=====================
-
include::glossary.txt[]
Notes and todo list for this manual