X-Git-Url: http://git.sourceforge.jp/view?p=tortoisegit%2FTortoiseGitJp.git;a=blobdiff_plain;f=doc%2Fsource%2Fen%2FTortoiseGit%2Fgit_doc%2Fuser-manual.xml;fp=doc%2Fsource%2Fen%2FTortoiseGit%2Fuser-manual.xml;h=268c845e91903805aca2acfe2dde74e82b34f5a5;hp=d42d0c53d82227599bf40ab89951af6cebc95983;hb=56a54239e080f7b15ea8641aa2edcc7b50ff739b;hpb=1ec3cf48363ff3dc673757f04ee9a2ca909e4baa
diff --git a/doc/source/en/TortoiseGit/user-manual.xml b/doc/source/en/TortoiseGit/git_doc/user-manual.xml
similarity index 95%
rename from doc/source/en/TortoiseGit/user-manual.xml
rename to doc/source/en/TortoiseGit/git_doc/user-manual.xml
index d42d0c5..268c845 100644
--- a/doc/source/en/TortoiseGit/user-manual.xml
+++ b/doc/source/en/TortoiseGit/git_doc/user-manual.xml
@@ -27,9 +27,9 @@ pages, or git-help(1) command. For example,
without any explanation.
Finally, see for ways that you can help make this manual more
complete.
-
+Repositories and Branches
-
+How to get a git repositoryIt will be useful to have a git repository to experiment with as you
read this manual.
@@ -48,8 +48,8 @@ directory, you will see that it contains a copy of the project files,
called the working tree, together with a special
top-level directory named ".git", which contains all the information
about the history of the project.
-
-
+
+How to check out a different version of a projectGit is best thought of as a tool for storing the history of a collection
of files. It stores the history as a compressed collection of
@@ -100,8 +100,8 @@ the current branch to point at v2.6.17 instead, with
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.
-
-
+
+Understanding History: CommitsEvery change in the history of a project is represented by a commit.
The git-show(1) command shows the most recent commit on the
@@ -143,7 +143,7 @@ without its name also changing.In fact, in we shall see that everything stored in git
history, including file data and directory contents, is stored in an object
with a name that is a hash of its contents.
-
+Understanding history: commits, parents, and reachabilityEvery commit (except the very first commit in a project) also has a
parent commit which shows what happened before this commit.
@@ -162,8 +162,8 @@ commits will help understand how the git organizes history.
if commit X is an ancestor of commit Y. Equivalently, you could say
that Y is a descendant of X, or that there is a chain of parents
leading from commit Y to commit X.
-
-
+
+Understanding history: History diagramsWe will sometimes represent git history using diagrams like the one
below. Commits are shown as "o", and the links between them with
@@ -175,8 +175,8 @@ lines drawn with - / and \. Time goes left to right:
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?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
@@ -186,9 +186,9 @@ the line of three commits leading up to that point as all being part of
"branch A".However, when no confusion will result, we often just use the term
"branch" both for branches and for branch heads.
-
-
-
+
+
+Manipulating branchesCreating, deleting, and modifying branches is quick and easy; here’s
a summary of the commands:
@@ -280,8 +280,8 @@ branch. In fact, git uses a file named "HEAD" in the .git directory to
remember which branch is current:
$ cat .git/HEAD
ref: refs/heads/master
-
-
+
+Examining an old version without creating a new branchThe git-checkout command normally expects a branch head, but will also
accept an arbitrary commit; for example, you can check out the commit
@@ -303,8 +303,8 @@ $ git branch
This is an easy way to check out a particular version without having to
make up a name for the new branch. You can still create a new branch
(or tag) for this version later if you decide to.
-
-
+
+Examining branches from a remote repositoryThe "master" branch that was created at the time you cloned is a copy
of the HEAD in the repository that you cloned from. That repository
@@ -325,8 +325,8 @@ examine them on a branch of your own, just as you would a tag:$ git checkout -b my-todo-copy origin/todoNote that the name "origin" is just the name that git uses by default
to refer to the repository that you cloned from.
-
-
+
+Naming branches, tags, and other referencesBranches, remote-tracking branches, and tags are all references to
commits. All references are named with a slash-separated path name
@@ -362,8 +362,8 @@ is usually a shortcut for the HEAD branch in the repository "origin".
the order it uses to decide which to choose when there are multiple
references with the same shorthand name, see the "SPECIFYING
REVISIONS" section of git-rev-parse(1).
-
-
+
+Updating a repository with git-fetchEventually the developer cloned from will do additional work in her
repository, creating new commits and advancing the branches to point
@@ -372,8 +372,8 @@ at the new commits.
remote-tracking branches to the latest version found in her
repository. It will not touch any of your own branches—not even the
"master" branch that was created for you on clone.
-
-
+
+Fetching branches from other repositoriesYou can also track branches from repositories other than the one you
cloned from, using git-remote(1):
@@ -400,9 +400,9 @@ a new stanza:
or delete these configuration options by editing .git/config with a
text editor. (See the "CONFIGURATION FILE" section of
git-config(1) for details.)
-
-
-
+
+
+Exploring git historyGit is best thought of as a tool for storing the history of a
collection of files. It does this by storing compressed snapshots of
@@ -412,7 +412,7 @@ the relationships between these snapshots.
history of a project.
We start with one specialized tool that is useful for finding the
commit that introduced a bug into a project.
-
+How to use bisect to find a regressionSuppose version 2.6.18 of your project worked, but the version at
"master" crashes. Sometimes the best way to find the cause of such a
@@ -464,8 +464,8 @@ bad one between some first skipped commits and a later bad commit.
test script that can tell a good from a bad commit. See
git-bisect(1) for more information about this and other "git
bisect" features.
-
-
+
+Naming commitsWe have seen several ways of naming commits already:
@@ -524,8 +524,8 @@ occasionally useful for translating some name for a commit to the object
name for that commit:
$ git rev-parse origin
e05db0fd4f31dde7005f075a84f96b360d05984b
-
-
+
+Creating tagsWe can also create a tag to refer to a particular commit; after
running
@@ -535,8 +535,8 @@ running
comment with the tag, and possibly sign it cryptographically, then you
should create a tag object instead; see the git-tag(1) man page
for details.
-
-
+
+Browsing revisionsThe git-log(1) command can show lists of commits. On its
own, it shows all commits reachable from the parent commit; but you
@@ -562,8 +562,8 @@ display options.
backwards through the parents; however, since git history can contain
multiple independent lines of development, the particular order that
commits are listed in may be somewhat arbitrary.
-
-
+
+Generating diffsYou can generate diffs between any two versions using
git-diff(1):
@@ -577,8 +577,8 @@ use git-format-patch(1):
$ git format-patch master..testwill generate a file with a patch for each commit reachable from test
but not from master.
-
-
+
+Viewing old file versionsYou can always view an old version of a file by just checking out the
correct revision first. But sometimes it is more convenient to be
@@ -587,10 +587,10 @@ anything out; this command does that:$ git show v2.5:fs/locks.cBefore the colon may be anything that names a commit, and after it
may be any path to a file tracked by git.
-
-
+
+Examples
-
+Counting the number of commits on a branchSuppose you want to know how many commits you’ve made on "mybranch"
since it diverged from "origin":
@@ -599,8 +599,8 @@ since it diverged from "origin":
lower-level command git-rev-list(1), which just lists the SHA1’s
of all the given commits:
$ git rev-list origin..mybranch | wc -l
-
-
+
+Check whether two branches point at the same historySuppose you want to check whether two branches point at the same point
in history.
@@ -618,8 +618,8 @@ contained reachable from either one reference or the other but not
both: so
$ git log origin...masterwill return no commits when the two branches are equal.
-
-
+
+Find first tagged version including a given fixSuppose you know that the commit e05db0fd fixed a certain problem.
You’d like to find the earliest tagged release that contains that
@@ -668,8 +668,8 @@ available
available
Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and
from v1.5.0-rc2, but not from v1.5.0-rc0.
-
-
+
+Showing commits unique to a given branchSuppose you would like to see all the commits reachable from the branch
head named "master" but not from any other head in your repository.
@@ -697,8 +697,8 @@ commits reachable from some head but not from any tag in the repository:$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )
(See git-rev-parse(1) for explanations of commit-selecting
syntax such as --not.)
-
-
+
+Creating a changelog and tarball for a software releaseThe git-archive(1) command can create a tar or zip archive from
any version of a project; for example:
@@ -724,8 +724,8 @@ echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"
echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"
and then he just cut-and-pastes the output commands after verifying that
they look OK.
-
-
+
+Finding commits referencing a file with given contentSomebody hands you a copy of a file, and asks which commits modified a
file such that it contained the given content either before or after the
@@ -735,12 +735,12 @@ commit. You can find out with this:Figuring out why this works is left as an exercise to the (advanced)
student. The git-log(1), git-diff-tree(1), and
git-hash-object(1) man pages may prove helpful.
-
-
-
-
+
+
+
+Developing with git
-
+Telling git your nameBefore creating any commits, you should introduce yourself to git. The
easiest way to do so is to make sure the following lines appear in a
@@ -750,8 +750,8 @@ file named .gitconfig in your home directory:
email = you@yourdomain.example.com
(See the "CONFIGURATION FILE" section of git-config(1) for
details on the configuration file.)
-
-
+
+Creating a new repositoryCreating a new repository from scratch is very easy:$ mkdir project
@@ -763,8 +763,8 @@ $ cd project
$ git init
$ git add . # include everything below ./ in the first commit:
$ git commit
-
-
+
+How to make a commitCreating a new commit takes three steps:
@@ -833,8 +833,8 @@ $ git status # a brief per-file summary of the above.
the index and the working tree files, and individually select diff hunks
for inclusion in the index (by right-clicking on the diff hunk and
choosing "Stage Hunk For Commit").
-
-
+
+Creating good commit messagesThough not required, it’s a good idea to begin the commit message
with a single short (less than 50 character) line summarizing the
@@ -842,8 +842,8 @@ change, followed by a blank line and then a more thorough
description. Tools that turn commits into email, for example, use
the first line on the Subject line and the rest of the commit in the
body.
-
-
+
+Ignoring filesA project will often generate files that you do not want to track with git.
This typically includes files generated by a build process or temporary
@@ -876,8 +876,8 @@ them in a file in your repository named .git/info/exclude, or in any file
specified by the core.excludesfile configuration variable. Some git
commands can also take exclude patterns directly on the command line.
See gitignore(5) for the details.
-
-
+
+How to mergeYou can rejoin two diverging branches of development using
git-merge(1):
@@ -898,8 +898,8 @@ creating a new file.
If you examine the resulting commit using gitk, you will see that it
has two parents, one pointing to the top of the current branch, and
one to the top of the other branch.
-
-
+
+Resolving a mergeWhen a merge isn’t resolved automatically, git leaves the index and
the working tree in a special state that gives you all the
@@ -925,7 +925,7 @@ default message unchanged, but you may add additional commentary of
your own if desired.The above is all you need to know to resolve a simple merge. But git
also provides more information to help resolve conflicts:
-
+Getting conflict-resolution help during a mergeAll of the changes that git was able to merge automatically are
already added to the index file, so git-diff(1) shows only
@@ -996,9 +996,9 @@ unmerged files using external tools such as Emacs or kdiff3.$ git add file.txtthe different stages of that file will be "collapsed", after which
git-diff will (by default) no longer show diffs for that file.
-
-
-
+
+
+Undoing a mergeIf you get stuck and decide to just give up and throw the whole mess
away, you can always return to the pre-merge state with
@@ -1009,8 +1009,8 @@ away, you can always return to the pre-merge state with
throw away a commit you have already committed if that commit may
itself have been merged into another branch, as doing so may confuse
further merges.
-
-
+
+Fast-forward mergesThere is one special case not mentioned above, which is treated
differently. Normally, a merge results in a merge commit, with two
@@ -1021,8 +1021,8 @@ commit present in the one is already contained in the other—then git
just performs a "fast forward"; the head of the current branch is moved
forward to point at the head of the merged-in branch, without any new
commits being created.
-
-
+
+Fixing mistakesIf you’ve messed up the working tree, but haven’t yet committed your
mistake, you can return the entire working tree to the last committed
@@ -1048,7 +1048,7 @@ You can go back and modify the old commit. You should
-
+Fixing a mistake with a new commitCreating a new commit that reverts an earlier change is very easy;
just pass the git-revert(1) command a reference to the bad
@@ -1062,8 +1062,8 @@ will be given a chance to edit the commit message for the new commit.
intact any changes made since then. If more recent changes overlap
with the changes to be reverted, then you will be asked to fix
conflicts manually, just as in the case of resolving a merge.
-
-
+
+Fixing a mistake by rewriting historyIf the problematic commit is the most recent commit, and you have not
yet made that commit public, then you may just
@@ -1080,8 +1080,8 @@ that case.It is also possible to replace commits further back in the history, but
this is an advanced topic to be left for
another chapter.
-
-
+
+Checking out an old version of a fileIn the process of undoing a previous bad change, you may find it
useful to check out an older version of a particular file using
@@ -1096,8 +1096,8 @@ modifying the working directory, you can do that with
git-show(1):$ git show HEAD^:path/to/filewhich will display the given version of the file.
-
-
+
+Temporarily setting aside work in progressWhile you are in the middle of working on something complicated, you
find an unrelated but obvious and trivial bug. You would like to fix it
@@ -1114,9 +1114,9 @@ $ git commit -a -m "blorpl: typofix"
After that, you can go back to what you were working on with
git stash apply:$ git stash apply
-
-
-
+
+
+Ensuring good performanceOn large repositories, git depends on compression to keep the history
information from taking up too much space on disk or in memory.
@@ -1125,10 +1125,10 @@ should occasionally run git-gc(1):
$ git gcto recompress the archive. This can be very time-consuming, so
you may prefer to run git-gc when you are not doing other work.
-
-
+
+Ensuring reliability
-
+Checking the repository for corruptionThe git-fsck(1) command runs a number of self-consistency checks
on the repository, and reports on any problems. This may take some
@@ -1146,10 +1146,10 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
Dangling objects are not a problem. At worst they may take up a little
extra disk space. They can sometimes provide a last-resort method for
recovering lost work—see for details.
-
-
+
+Recovering lost changes
-
+ReflogsSay you modify a branch with git-reset(1) --hard, and then
realize that the branch was the only reference you had to that point in
@@ -1179,8 +1179,8 @@ section of git-rev-parse(1) for details.
While normal history is shared by every repository that works on the
same project, the reflog history is not shared: it tells you only about
how the branches in your local repository have changed over time.
-
-
+
+Examining dangling objectsIn some situations the reflog may not be able to save you. For example,
suppose you delete a branch, then realize you need the history it
@@ -1208,13 +1208,13 @@ reference pointing to it, for example, a new branch:$ git branch recovered-branch 7281251dddOther types of dangling objects (blobs and trees) are also possible, and
dangling objects can arise in other situations.
-
-
-
-
-
+
+
+
+
+Sharing development with others
-
+Getting updates with git-pullAfter you clone a repository and make a few changes of your own, you
may wish to check the original repository for updates and merge them
@@ -1248,8 +1248,8 @@ the commands$ git pull . branch
$ git merge branchare roughly equivalent. The former is actually very commonly used.
-
-
+
+Submitting patches to a projectIf you just have a few changes, the simplest way to submit them may
just be to send them as patches in email:
@@ -1262,8 +1262,8 @@ hand. However, if you have a lot to send at once, you may prefer to
use the git-send-email(1) script to automate the process.
Consult the mailing list for your project first to determine how they
prefer such patches be handled.
-
-
+
+Importing patches to a projectGit also provides a tool called git-am(1) (am stands for
"apply mailbox"), for importing such an emailed series of patches.
@@ -1283,8 +1283,8 @@ remaining patches from the mailbox.The final result will be a series of commits, one for each patch in
the original mailbox, with authorship and commit log message each
taken from the message containing each patch.
-
-
+
+Public git repositoriesAnother way to submit changes to a project is to tell the maintainer
of that project to pull the changes from your repository using
@@ -1321,7 +1321,7 @@ your personal repo ------------------> your public repo
| they push V
their public repo <------------------- their repo
We explain how to do this in the following sections.
-
+Setting up a public repositoryAssume your personal repository is in the directory ~/proj. We
first create a new clone of the repository and tell git-daemon that it
@@ -1334,8 +1334,8 @@ around it.Next, copy proj.git to the server where you plan to host the
public repository. You can use scp, rsync, or whatever is most
convenient.
-
-
+
+Exporting a git repository via the git protocolThis is the preferred method.If someone else administers the server, they should tell you what
@@ -1350,8 +1350,8 @@ arguments will further restrict the exports to those paths.You can also run git-daemon as an inetd service; see the
git-daemon(1) man page for details. (See especially the
examples section.)
-
-
+
+Exporting a git repository via httpThe git protocol gives better performance and reliability, but on a
host with a web server set up, http exports may be simpler to set up.
@@ -1371,8 +1371,8 @@ clone or pull from that URL, for example with a command line like:
setup-git-server-over-http
for a slightly more sophisticated setup using WebDAV which also
allows pushing over http.)
-
-
+
+Pushing changes to a public repositoryNote that the two techniques outlined above (exporting via
http or git) allow other
@@ -1404,8 +1404,8 @@ EOF
See the explanations of the remote.<name>.url, branch.<name>.remote,
and remote.<name>.push options in git-config(1) for
details.
-
-
+
+What to do when a push failsIf a push would not result in a fast forward of the
remote branch, then it will fail with an error like:
@@ -1450,8 +1450,8 @@ solution is to retry the push after first updating your work: either by a
pull, or by a fetch followed by a rebase; see the
next section and
gitcvs-migration(7) for more.
-
-
+
+Setting up a shared repositoryAnother way to collaborate is by using a model similar to that
commonly used in CVS, where several developers with special rights
@@ -1491,17 +1491,17 @@ The lack of a central group of "committers" means there is
-
-
+
+Allowing web browsing of a repositoryThe gitweb cgi script provides users an easy way to browse your
project’s files and history without having to install git; see the file
gitweb/INSTALL in the git source tree for instructions on setting it up.
-
-
-
+
+
+Examples
-
+Maintaining topic branches for a Linux subsystem maintainerThis describes how Tony Luck uses git in his role as maintainer of the
IA64 architecture for the Linux kernel.
@@ -1714,17 +1714,17 @@ do
esac
git log origin/master..$branch | git shortlog
done
-
-
-
-
+
+
+
+Rewriting history and maintaining patch seriesNormally commits are only added to a project, never taken away or
replaced. Git is designed with this assumption, and violating it will
cause git’s merge machinery (for example) to do the wrong thing.However, there is a situation in which it can be useful to violate this
assumption.
-
+Creating the perfect patch seriesSuppose you are a contributor to a large project, and you want to add a
complicated feature, and to present it to the other developers in a way
@@ -1764,8 +1764,8 @@ The complete series produces the same end result as your own
We will introduce some tools that can help you do this, explain how to
use them, and then explain some of the problems that can arise because
you are rewriting history.
-
-
+
+Keeping a patch series up to date using git-rebaseSuppose that you create a branch "mywork" on a remote-tracking branch
"origin", and create some commits on top of it:
@@ -1811,8 +1811,8 @@ running git-commit, just run
At any point you may use the --abort option to abort this process and
return mywork to the state it had before you started the rebase:$ git rebase --abort
-
-
+
+Rewriting a single commitWe saw in that you can replace the
most recent commit using
@@ -1839,8 +1839,8 @@ then clean up with
Note that the immutable nature of git history means that you haven’t really
"modified" existing commits; instead, you have replaced the old commits with
new commits having new object names.
-
-
+
+Reordering or selecting from a patch seriesGiven one existing commit, the git-cherry-pick(1) command
allows you to apply the change introduced by that commit and create a
@@ -1860,14 +1860,14 @@ patches, then reset the state to before the patches:
$ git reset --hard origin
Then modify, reorder, or eliminate patches as preferred before applying
them again with git-am(1).
-
-
+
+Other toolsThere are numerous other tools, such as StGIT, which exist for the
purpose of maintaining a patch series. These are outside of the scope of
this manual.
-
-
+
+Problems with rewriting historyThe primary problem with rewriting the history of a branch has to do
with merging. Suppose somebody fetches your branch and merges it into
@@ -1899,8 +1899,8 @@ order to examine or test them, but they should not attempt to pull such
branches into their own work.For true distributed development that supports proper merging,
published branches should never be rewritten.
-
-
+
+Why bisecting merge commits can be harder than bisecting linear historyThe git-bisect(1) command correctly handles history that
includes merge commits. However, when the commit that it finds is a
@@ -1948,11 +1948,11 @@ and understanding why Y* was broken would probably be easier.
working on an otherwise merge-heavy project, keep the history
linear by rebasing against the latest upstream version before
publishing.
-
-
-
+
+
+Advanced branch management
-
+Fetching individual branchesInstead of using git-remote(1), you can also choose just
to update one branch at a time, and to store it locally under an
@@ -1969,8 +1969,8 @@ branch named "master" from the repository at the given URL. If you
already have a branch named example-master, it will attempt to
fast-forward to the commit given by example.com’s
master branch. In more detail:
-
-
+
+git fetch and fast-forwardsIn the previous example, when updating an existing branch, "git-fetch"
checks to make sure that the most recent commit on the remote
@@ -1994,8 +1994,8 @@ described in the following section. However, note that in the
situation above this may mean losing the commits labeled "a" and "b",
unless you’ve already created a reference of your own pointing to
them.
-
-
+
+Forcing git-fetch to do non-fast-forward updatesIf git fetch fails because the new head of a branch is not a
descendant of the old head, you may force the update with:
@@ -2005,8 +2005,8 @@ flag to force updates of all the fetched branches, as in:
$ git fetch -f originBe aware that commits that the old version of example/master pointed at
may be lost, as we saw in the previous section.
-
-
+
+Configuring remote branchesWe saw above that "origin" is just a shortcut to refer to the
repository that you originally cloned from. This information is
@@ -2042,15 +2042,15 @@ directly editing the file .git/config instead of using
git-config(1).See git-config(1) for more details on the configuration
options mentioned above.
-
-
-
+
+
+Git conceptsGit is built on a small number of simple but powerful ideas. While it
is possible to get things done without understanding them, you will find
git much more intuitive if you do.We start with the most important, the object database and the index.
-
+The Object DatabaseWe already saw in that all commits are stored
under a 40-digit "object name". In fact, all the information needed to
@@ -2118,7 +2118,7 @@ A "tag" object symbolically identifies and
The object types in some more detail:
-
+Commit ObjectThe "commit" object links a physical state of a tree with a description
of how we got there and why. Use the --pretty=raw option to
@@ -2183,8 +2183,8 @@ file data at changing paths suggests a rename. (See, for example, the
A commit is usually created by git-commit(1), which creates a
commit whose parent is normally the current HEAD, and whose tree is
taken from the content currently stored in the index.
-
-
+
+Tree ObjectThe ever-versatile git-show(1) command can also be used to
examine tree objects, but git-ls-tree(1) will give you more
@@ -2214,8 +2214,8 @@ identical object names.
entries. See for documentation.)
Note that the files all have mode 644 or 755: git actually only pays
attention to the executable bit.
-
-
+
+Blob ObjectYou can use git-show(1) to examine the contents of a blob; take,
for example, the blob in the entry for "COPYING" from the tree above:
@@ -2236,8 +2236,8 @@ renaming a file does not change the object that file is associated with.git-show(1) with the <revision>:<path> syntax. This can
sometimes be useful for browsing the contents of a tree that is not
currently checked out.
-
-
+
+TrustIf you receive the SHA1 name of a blob from one source, and its contents
from another (possibly untrusted) source, you can still trust that those
@@ -2260,8 +2260,8 @@ sending out a single email that tells the people the name (SHA1 hash)
of the top commit, and digitally sign that email using something
like GPG/PGP.To assist in this, git also provides the tag object…
-
-
+
+Tag ObjectA tag object contains an object, object type, tag name, the name of the
person ("tagger") who created the tag, and a message, which may contain
@@ -2284,8 +2284,8 @@ nLE/L9aUXdWeTFPron96DLA=
objects. (Note that git-tag(1) can also be used to create
"lightweight tags", which are not tag objects at all, but just simple
references whose names begin with "refs/tags/").
-
-
+
+How git stores objects efficiently: pack filesNewly created objects are initially created in a file named after the
object’s SHA1 hash (stored in .git/objects).
@@ -2323,8 +2323,8 @@ You can verify that the loose objects are gone by looking at the
objects will work exactly as they did before.
The git-gc(1) command performs packing, pruning, and more for
you, so is normally the only high-level command you need.
-
-
+
+Dangling objectsThe git-fsck(1) command will sometimes complain about dangling
objects. They are not a problem.
@@ -2384,8 +2384,8 @@ Running it while somebody is actually changing the repository can cause
confusing and scary messages, but it won’t actually do anything bad. In
contrast, running "git prune" while somebody is actively changing the
repository is a BAD idea).
-
-
+
+Recovering from repository corruptionBy design, git treats data trusted to it with caution. However, even in
the absence of bugs in git itself, it is still possible that hardware or
@@ -2464,9 +2464,9 @@ shot at reconstructing the contents of the in-between state 4b9458b.and just looked for the sha of the missing object (4b9458b..) in that
whole thing. It’s up to you - git does have a lot of information, it is
just missing one particular blob version.
-
-
-
+
+
+The indexThe index is a binary file (generally kept in .git/index) containing a
sorted list of path names, each with permissions and the SHA1 of a blob
@@ -2524,9 +2524,9 @@ conflicts.
a tree which you are in the process of working on.
If you blow the index away entirely, you generally haven’t lost any
information as long as you have the name of the tree that it described.
-
-
-
+
+
+SubmodulesLarge projects are often composed of smaller, self-contained modules. For
example, an embedded Linux distribution’s source tree would include every
@@ -2667,7 +2667,7 @@ $ git commit -m "Updated submodule a."
$ git push
You have to run git submodule update after git pull if you want to update
submodules, too.
-
+Pitfalls with submodulesAlways publish the submodule change before publishing the change to the
superproject that references it. If you forget to publish the submodule change,
@@ -2702,15 +2702,15 @@ $ cat a.txt
module a
The changes are still visible in the submodule’s reflog.This is not the case if you did not commit your changes.
-
-
-
+
+
+Low-level git operationsMany of the higher-level commands were originally implemented as shell
scripts using a smaller core of low-level git commands. These can still
be useful when doing unusual things with git, or just as a way to
understand its inner workings.
-
+Object access and manipulationThe git-cat-file(1) command can show the contents of any object,
though the higher-level git-show(1) is usually more useful.
@@ -2722,8 +2722,8 @@ accessed by git-ls-tree(1). Two trees can
A tag is created with git-mktag(1), and the signature can be
verified by git-verify-tag(1), though it is normally simpler to
use git-tag(1) for both.
-
-
+
+The WorkflowHigh-level operations such as git-commit(1),
git-checkout(1) and git-reset(1) work by moving data
@@ -2735,7 +2735,7 @@ work purely on the index file (showing the cu
index), but most operations move data between the index file and either
the database or the working directory. Thus there are four main
combinations:
-
+working directory → indexThe git-update-index(1) command updates the index with
information from the working directory. You generally update the
@@ -2761,8 +2761,8 @@ it will only update the fields that are used to quickly test whether
an object still matches its old backing store object.The previously introduced git-add(1) is just a wrapper for
git-update-index(1).
-
-
+
+index → object databaseYou write your current index file to a "tree" object with the program$ git write-tree
@@ -2771,8 +2771,8 @@ current index into the set of tree objects that describe that state,
and it will return the name of the resulting top-level tree. You can
use that tree to re-generate the index at any time by going in the
other direction:
-
-
+
+object database → indexYou read a "tree" file from the object database, and use that to
populate (and overwrite—don’t do this if your index contains any
@@ -2782,8 +2782,8 @@ index. Normal operation is justand your index file will now be equivalent to the tree that you saved
earlier. However, that is only your index file: your working
directory contents have not been modified.
-
-
+
+index → working directoryYou update your working directory from the index by "checking out"
files. This is not a very common operation, since normally you’d just
@@ -2802,8 +2802,8 @@ need to use the "-f" flag (before the "-a" flag or the file
force the checkout.Finally, there are a few odds and ends which are not purely moving
from one representation to the other:
-
-
+
+Tying it all togetherTo commit a tree you have instantiated with "git write-tree", you’d
create a "commit" object that refers to that tree and the history
@@ -2861,9 +2861,9 @@ various pieces fit together.
| Working |
| Directory |
+-----------+
-
-
-
+
+
+Examining the dataYou can examine the data represented in the object database and the
index with various helper tools. For every object, you can use
@@ -2883,8 +2883,8 @@ follow the convention of having the top commit name in .git/HEAD
$ git cat-file commit HEADto see what the top commit was.
-
-
+
+Merging multiple treesGit helps you do a three-way merge, which you can expand to n-way by
repeating the merge procedure arbitrary times until you finally
@@ -2916,8 +2916,8 @@ you have in your current index anyway).which will do all trivial merge operations for you directly in the
index file, and you can just write the result out with
git write-tree.
-
-
+
+Merging multiple trees, continuedSadly, many merges aren’t trivial. If there are files that have
been added, moved or removed, or if both branches have modified the
@@ -2966,13 +2966,13 @@ for this. There is a git-merge-index program that extracts t
stages to temporary files and calls a "merge" script on it:$ git merge-index git-merge-one-file hello.cand that is what higher level git-merge -s resolve is implemented with.
-
-
-
+
+
+Hacking gitThis chapter covers internal details of the git implementation which
probably only git developers need to understand.
-
+Object storage formatAll objects have a statically determined "type" which identifies the
format of the object (i.e. how it is used, and how it can refer to other
@@ -2998,8 +2998,8 @@ connectivity to other objects verified. This is generally done with
the git-fsck program, which generates a full dependency graph
of all objects, and verifies their internal consistency (in addition
to just verifying their superficial consistency through the hash).
-
-
+
+A birds-eye view of Git’s source codeIt is not always easy for new developers to find their way through Git’s
source code. This section gives you a little guidance to show where to
@@ -3171,9 +3171,9 @@ builtin:$ git log --no-merges --diff-filter=A builtin-*.cYou see, Git is actually the best tool to find out about the source of Git
itself!
-
-
-
+
+
+GIT Glossary
@@ -4137,12 +4137,12 @@ This commit is referred to as a "merge commit", or sometimes just a
-
+
Git Quick ReferenceThis is a quick summary of the major commands; the previous chapters
explain how these work in more detail.
-
+Creating a new repositoryFrom a tarball:$ tar xzf project.tar.gz
@@ -4154,8 +4154,8 @@ $ git commitFrom a remote repository:$ git clone git://example.com/pub/project.git
$ cd project
-
-
+
+Managing branches$ git branch # list all local branches in this repo
$ git checkout test # switch working directory to branch "test"
@@ -4194,8 +4194,8 @@ $ git remote show example # get details
...
$ git fetch example # update branches from example
$ git branch -r # list all remote branches
-
-
+
+Exploring history$ gitk # visualize and browse history
$ git log # list all commits
@@ -4222,8 +4222,8 @@ Bisecting: 675 revisions left to test after this
$ git bisect good # if this revision is good, or
$ git bisect bad # if this revision is bad.
# repeat until done.
-
-
+
+Making changesMake sure git knows who to blame:$ cat >>~/.gitconfig <<\EOF
@@ -4240,15 +4240,15 @@ $ git commitOr, prepare and create the commit in one step:$ git commit d.txt # use latest content only of d.txt
$ git commit -a # use latest content of all tracked files
-
-
+
+Merging$ git merge test # merge branch "test" into the current branch
$ git pull git://example.com/project.git master
# fetch and merge in remote branch
$ git pull . test # equivalent to git merge test
-
-
+
+Sharing your changesImporting or exporting patches:$ git format-patch origin..HEAD # format a patch for each commit
@@ -4268,14 +4268,14 @@ branch with your commits:
Shortcut version for a frequently used remote repository:$ git remote add example ssh://example.com/project.git
$ git push example test
-
-
+
+Repository maintenanceCheck for corruption:$ git fsckRecompress, remove unused cruft:$ git gc
-
+
Notes and todo list for this manual