Git is a fast distributed revision control system.
This manual is designed to be readable by someone with basic UNIX
-command-line skills, but no previous knowledge of git.
+command-line skills, but no previous knowledge of Git.
<<repositories-and-branches>> and <<exploring-git-history>> explain how
to fetch and study a project using git--read these chapters to learn how
With the latter, you can use the manual viewer of your choice; see
linkgit:git-help[1] for more information.
-See also <<git-quick-start>> for a brief overview of git commands,
+See also <<git-quick-start>> for a brief overview of Git commands,
without any explanation.
Finally, see <<todo>> for ways that you can help make this manual more
=========================
[[how-to-get-a-git-repository]]
-How to get a git repository
+How to get a Git repository
---------------------------
-It will be useful to have a git repository to experiment with as you
+It will be useful to have a Git repository to experiment with as you
read this manual.
The best way to get one is by using the linkgit:git-clone[1] command to
project in mind, here are some interesting examples:
------------------------------------------------
- # git itself (approx. 10MB download):
+ # Git itself (approx. 10MB download):
$ git clone git://git.kernel.org/pub/scm/git/git.git
# the Linux kernel (approx. 150MB download):
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
Git 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
-interrelated snapshots of the project's contents. In git each such
+interrelated snapshots of the project's contents. In Git each such
version is called a <<def_commit,commit>>.
Those snapshots aren't necessarily all arranged in a single line from
parallel lines of development, called <<def_branch,branches>>, which may
merge and diverge.
-A single git repository can track development on multiple branches. It
+A single Git repository can track development on multiple branches. It
does this by keeping a list of <<def_head,heads>> which reference the
latest commit on each branch; the linkgit:git-branch[1] command shows
you the list of branch heads:
contents of the commit, you are guaranteed that the commit can never change
without its name also changing.
-In fact, in <<git-concepts>> we shall see that everything stored in git
+In fact, in <<git-concepts>> 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.
Following the chain of parents will eventually take you back to the
beginning of the project.
-However, the commits do not form a simple list; git allows lines of
+However, the commits do not form a simple list; Git allows lines of
development to diverge and then reconverge, and the point where two
lines of development reconverge is called a "merge". The commit
representing a merge can therefore have more than one parent, with
of development leading to that point.
The best way to see how this works is using the linkgit:gitk[1]
-command; running gitk now on a git repository and looking for merge
-commits will help understand how the git organizes history.
+command; running gitk now on a Git repository and looking for merge
+commits will help understand how the Git organizes history.
In the following, we say that commit X is "reachable" from commit Y
if commit X is an ancestor of commit Y. Equivalently, you could say
Understanding history: History diagrams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-We will sometimes represent git history using diagrams like the one
+We will sometimes represent Git history using diagrams like the one
below. Commits are shown as "o", and the links between them with
lines drawn with - / and \. Time goes left to right:
even if the branch points to a commit not reachable
from the current branch, you may know that that commit
is still reachable from some other branch or tag. In that
- case it is safe to use this command to force git to delete
+ case it is safe to use this command to force Git to delete
the branch.
git checkout <branch>::
make the current branch <branch>, updating the working
check it out.
The special symbol "HEAD" can always be used to refer to the current
-branch. In fact, git uses a file named "HEAD" in the .git directory to
+branch. In fact, Git uses a file named "HEAD" in the .git directory to
remember which branch is current:
------------------------------------------------
You can also check out "origin/todo" directly to examine it or
write a one-off patch. See <<detached-head,detached head>>.
-Note that the name "origin" is just the name that git uses by default
+Note that the name "origin" is just the name that Git uses by default
to refer to the repository that you cloned from.
[[how-git-stores-references]]
to just using the name of that repository. So, for example, "origin"
is usually a shortcut for the HEAD branch in the repository "origin".
-For the complete list of paths which git checks for references, and
+For the complete list of paths which Git checks for references, and
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 linkgit:gitrevisions[7].
If you run "git fetch <remote>" later, the remote-tracking branches for the
named <remote> will be updated.
-If you examine the file .git/config, you will see that git has added
+If you examine the file .git/config, you will see that Git has added
a new stanza:
-------------------------------------------------
...
-------------------------------------------------
-This is what causes git to track the remote's branches; you may modify
+This is what causes Git to track the remote's branches; you may modify
or delete these configuration options by editing .git/config with a
text editor. (See the "CONFIGURATION FILE" section of
linkgit:git-config[1] for details.)
[[exploring-git-history]]
-Exploring git history
+Exploring Git history
=====================
Git is best thought of as a tool for storing the history of a
[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
-------------------------------------------------
-If you run "git branch" at this point, you'll see that git has
+If you run "git branch" at this point, you'll see that Git has
temporarily moved you in "(no branch)". HEAD is now detached from any
branch and points directly to a commit (with commit id 65934...) that
is reachable from "master" but not from v2.6.18. Compile and test it,
[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
-------------------------------------------------
-checks out an older version. Continue like this, telling git at each
+checks out an older version. Continue like this, telling Git at each
stage whether the version it gives you is good or bad, and notice
that the number of revisions left to test is cut approximately in
half each time.
continue.
Instead of "git bisect visualize" and then "git reset --hard
-fb47ddb2db...", you might just want to tell git that you want to skip
+fb47ddb2db...", you might just want to tell Git that you want to skip
the current commit:
-------------------------------------------------
$ git bisect skip
-------------------------------------------------
-In this case, though, git may not eventually be able to tell the first
+In this case, though, Git may not eventually be able to tell the first
bad one between some first skipped commits and a later bad commit.
There are also ways to automate the bisecting process if you have a
display options.
Note that git log starts with the most recent commit and works
-backwards through the parents; however, since git history can contain
+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.
-------------------------------------------------
Before the colon may be anything that names a commit, and after it
-may be any path to a file tracked by git.
+may be any path to a file tracked by Git.
[[history-examples]]
Examples
Or you could recall that the ... operator selects all commits
contained reachable from either one reference or the other but not
-both: so
+both; so
-------------------------------------------------
$ git log origin...master
any version of a project; for example:
-------------------------------------------------
-$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
+$ git archive -o latest.tar.gz --prefix=project/ HEAD
-------------------------------------------------
-will use HEAD to produce a tar archive in which each filename is
-preceded by "project/".
+will use HEAD to produce a gzipped tar archive in which each filename
+is preceded by `project/`. The output file format is inferred from
+the output file extension if possible, see linkgit:git-archive[1] for
+details.
+
+Versions of Git older than 1.7.7 don't know about the 'tar.gz' format,
+you'll need to use gzip explicitly:
+
+-------------------------------------------------
+$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
+-------------------------------------------------
If you're releasing a new version of a software project, you may want
to simultaneously make a changelog to include in the release
linkgit:git-hash-object[1] man pages may prove helpful.
[[Developing-With-git]]
-Developing with git
+Developing with Git
===================
[[telling-git-your-name]]
-Telling git your name
+Telling Git your name
---------------------
-Before 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
-file named .gitconfig in your home directory:
+Before creating any commits, you should introduce yourself to Git.
+The easiest way to do so is to use linkgit:git-config[1]:
+
+------------------------------------------------
+$ git config --global user.name 'Your Name Comes Here'
+$ git config --global user.email 'you@yourdomain.example.com'
+------------------------------------------------
+
+Which will add the following to a file named `.gitconfig` in your
+home directory:
------------------------------------------------
[user]
email = you@yourdomain.example.com
------------------------------------------------
-(See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
-details on the configuration file.)
+See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
+details on the configuration file. The file is plain text, so you can
+also edit it with your favorite editor.
[[creating-a-new-repository]]
1. Making some changes to the working directory using your
favorite editor.
- 2. Telling git about your changes.
- 3. Creating the commit using the content you told git about
+ 2. Telling Git about your changes.
+ 3. Creating the commit using the content you told Git about
in step 2.
In practice, you can interleave and repeat steps 1 and 2 as many
times as you want: in order to keep track of what you want committed
-at step 3, git maintains a snapshot of the tree's contents in a
+at step 3, Git maintains a snapshot of the tree's contents in a
special staging area called "the index."
At the beginning, the content of the index will be identical to
$ git commit
-------------------------------------------------
-and git will prompt you for a commit message and then create the new
+and Git will prompt you for a commit message and then create the new
commit. Check to make sure it looks like what you expected with
-------------------------------------------------
change, followed by a blank line and then a more thorough
description. The text up to the first blank line in a commit
message is treated as the commit title, and that title is used
-throughout git. For example, linkgit:git-format-patch[1] turns a
+throughout Git. For example, linkgit:git-format-patch[1] turns a
commit into email, and it uses the title on the Subject line and the
rest of the commit in the body.
Ignoring files
--------------
-A project will often generate files that you do 'not' want to track with git.
+A 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
-backup files made by your editor. Of course, 'not' tracking files with git
+backup files made by your editor. Of course, 'not' tracking files with Git
is just a matter of 'not' calling `git add` on them. But it quickly becomes
annoying to have these untracked files lying around; e.g. they make
`git add .` practically useless, and they keep showing up in the output of
`git status`.
-You can tell git to ignore certain files by creating a file called .gitignore
+You can tell Git to ignore certain files by creating a file called .gitignore
in the top level of your working directory, with contents such as:
-------------------------------------------------
If you wish the exclude patterns to affect only certain repositories
(instead of every repository for a given project), you may instead put
them in a file in your repository named .git/info/exclude, or in any file
-specified by the `core.excludesfile` configuration variable. Some git
+specified by the `core.excludesfile` configuration variable. Some Git
commands can also take exclude patterns directly on the command line.
See linkgit:gitignore[5] for the details.
Conflict markers are left in the problematic files, and after
you resolve the conflicts manually, you can update the index
-with the contents and run git commit, as you normally would when
+with the contents and run Git commit, as you normally would when
creating a new file.
If you examine the resulting commit using gitk, you will see that it
Resolving a merge
-----------------
-When a merge isn't resolved automatically, git leaves the index and
+When a merge isn't resolved automatically, Git leaves the index and
the working tree in a special state that gives you all the
information you need to help resolve the merge.
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
+The above is all you need to know to resolve a simple merge. But Git
also provides more information to help resolve conflicts:
[[conflict-resolution]]
Getting conflict-resolution help during a merge
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-All of the changes that git was able to merge automatically are
+All of the changes that Git was able to merge automatically are
already added to the index file, so linkgit:git-diff[1] shows only
the conflicts. It uses an unusual syntax:
were merged.
However, if the current branch is a descendant of the other--so every
-commit present in the one is already contained in the other--then git
+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.
2. You can go back and modify the old commit. You should
never do this if you have already made the history public;
- git does not normally expect the "history" of a project to
+ Git does not normally expect the "history" of a project to
change, and cannot correctly perform repeated merges from
a branch that has had its history changed.
$ git revert HEAD^
-------------------------------------------------
-In this case git will attempt to undo the old change while leaving
+In this case Git will attempt to undo the old change while leaving
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,
Ensuring good performance
-------------------------
-On large repositories, git depends on compression to keep the history
-information from taking up too much space on disk or in memory.
-
-This compression is not performed automatically. Therefore you
-should occasionally run linkgit:git-gc[1]:
-
--------------------------------------------------
-$ git gc
--------------------------------------------------
-
-to recompress the archive. This can be very time-consuming, so
-you may prefer to run `git gc` when you are not doing other work.
+On large repositories, Git depends on compression to keep the history
+information from taking up too much space on disk or in memory. Some
+Git commands may automatically run linkgit:git-gc[1], so you don't
+have to worry about running it manually. However, compressing a large
+repository may take a while, so you may want to call `gc` explicitly
+to avoid automatic compression kicking in when it is not convenient.
[[ensuring-reliability]]
realize that the branch was the only reference you had to that point in
history.
-Fortunately, git also keeps a log, called a "reflog", of all the
+Fortunately, Git also keeps a log, called a "reflog", of all the
previous values of each branch. So in this case you can still find the
old history using, for example,
-------------------------------------------------
This lists the commits reachable from the previous version of the
-"master" branch head. This syntax can be used with any git command
+"master" branch head. This syntax can be used with any Git command
that accepts a commit, not just with git log. Some other examples:
-------------------------------------------------
how to control this pruning, and see the "SPECIFYING REVISIONS"
section of linkgit:gitrevisions[7] for details.
-Note that the reflog history is very different from normal git history.
+Note that the reflog history is very different from normal Git history.
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.
Git will apply each patch in order; if any conflicts are found, it
will stop, and you can fix the conflicts as described in
"<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells
-git to perform a merge; if you would prefer it just to abort and
+Git to perform a merge; if you would prefer it just to abort and
leave your tree and index untouched, you may omit that option.)
Once the index is updated with the results of the conflict
$ git am --resolved
-------------------------------------------------
-and git will create the commit for you and continue applying the
+and Git will create the commit for you and continue applying the
remaining patches from the mailbox.
The final result will be a series of commits, one for each patch in
taken from the message containing each patch.
[[public-repositories]]
-Public git repositories
+Public Git repositories
-----------------------
Another way to submit changes to a project is to tell the maintainer
convenient.
[[exporting-via-git]]
-Exporting a git repository via the git protocol
+Exporting a Git repository via the Git protocol
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the preferred method.
Otherwise, all you need to do is start linkgit:git-daemon[1]; it will
listen on port 9418. By default, it will allow access to any directory
-that looks like a git directory and contains the magic file
+that looks like a Git directory and contains the magic file
git-daemon-export-ok. Passing some directory paths as `git daemon`
arguments will further restrict the exports to those paths.
examples section.)
[[exporting-via-http]]
-Exporting a git repository via http
+Exporting a git repository via HTTP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 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.
+The 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.
-All you need to do is place the newly created bare git repository in
+All you need to do is place the newly created bare Git repository in
a directory that is exported by the web server, and make some
adjustments to give web clients some extra information they need:
(See also
link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
for a slightly more sophisticated setup using WebDAV which also
-allows pushing over http.)
+allows pushing over HTTP.)
[[pushing-changes-to-a-public-repository]]
Pushing changes to a public repository
Note that the target of a "push" is normally a
<<def_bare_repository,bare>> repository. You can also push to a
-repository that has a checked-out working tree, but the working tree
-will not be updated by the push. This may lead to unexpected results if
-the branch you push to is the currently checked-out branch!
+repository that has a checked-out working tree, but a push to update the
+currently checked-out branch is denied by default to prevent confusion.
+See the description of the receive.denyCurrentBranch option
+in linkgit:git-config[1] for details.
As with `git fetch`, you may also set up configuration options to
-save typing; so, for example, after
+save typing; so, for example:
+
+-------------------------------------------------
+$ git remote add public-repo ssh://yourserver.com/~you/proj.git
+-------------------------------------------------
+
+adds the following to `.git/config`:
-------------------------------------------------
-$ cat >>.git/config <<EOF
[remote "public-repo"]
- url = ssh://yourserver.com/~you/proj.git
-EOF
+ url = yourserver.com:proj.git
+ fetch = +refs/heads/*:refs/remotes/example/*
-------------------------------------------------
-you should be able to perform the above push with just
+which lets you do the same push with just
-------------------------------------------------
$ git push public-repo master
$ git push ssh://yourserver.com/~you/proj.git +master
-------------------------------------------------
+Note the addition of the `+` sign. Alternatively, you can use the
+`-f` flag to force the remote update, as in:
+
+-------------------------------------------------
+$ git push -f ssh://yourserver.com/~you/proj.git master
+-------------------------------------------------
+
Normally whenever a branch head in a public repository is modified, it
is modified to point to a descendant of the commit that it pointed to
before. By forcing a push in this situation, you break that convention.
linkgit:gitcvs-migration[7] for instructions on how to
set this up.
-However, while there is nothing wrong with git's support for shared
+However, while there is nothing wrong with Git's support for shared
repositories, this mode of operation is not generally recommended,
-simply because the mode of collaboration that git supports--by
+simply because the mode of collaboration that Git supports--by
exchanging patches and pulling from public repositories--has so many
advantages over the central shared repository:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 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.
+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.
[[sharing-development-examples]]
Examples
Maintaining topic branches for a Linux subsystem maintainer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This describes how Tony Luck uses git in his role as maintainer of the
+This describes how Tony Luck uses Git in his role as maintainer of the
IA64 architecture for the Linux kernel.
He uses two public branches:
Important note! If you have any local changes in these branches, then
this merge will create a commit object in the history (with no local
-changes git will simply do a "fast-forward" merge). Many people dislike
+changes Git will simply do a "fast-forward" merge). Many people dislike
the "noise" that this creates in the Linux history, so you should avoid
doing this capriciously in the "release" branch, as these noisy commits
will become part of the permanent history when you ask Linus to pull
these changes, just apply directly to the "release" branch, and then
merge that into the "test" branch.
-To create diffstat and shortlog summaries of changes to include in a "please
-pull" request to Linus you can use:
-
--------------------------------------------------
-$ git diff --stat origin..release
--------------------------------------------------
-
-and
+After pushing your work to `mytree`, you can use
+linkgit:git-request-pull[1] to prepare a "please pull" request message
+to send to Linus:
-------------------------------------------------
-$ git log -p origin..release | git shortlog
+$ git push mytree
+$ git request-pull origin mytree release
-------------------------------------------------
Here are some of the scripts that simplify all this even further.
-------------------------------------------------
==== update script ====
-# Update a branch in my GIT tree. If the branch to be updated
+# Update a branch in my Git tree. If the branch to be updated
# is origin, then pull from kernel.org. Otherwise merge
# origin/master branch into test|release branch
-------------------------------------------------
==== status script ====
-# report on status of my ia64 GIT tree
+# report on status of my ia64 Git tree
gb=$(tput setab 2)
rb=$(tput setab 1)
Normally 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.
+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.
$ git rebase --continue
-------------------------------------------------
-and git will continue applying the rest of the patches.
+and Git will continue applying the rest of the patches.
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
-------------------------------------------------
+If you need to reorder or edit a number of commits in a branch, it may
+be easier to use `git rebase -i`, which allows you to reorder and
+squash commits, as well as marking them for individual editing during
+the rebase. See <<interactive-rebase>> for details, and
+<<reordering-patch-series>> for alternatives.
+
[[rewriting-one-commit]]
Rewriting a single commit
-------------------------
which will replace the old commit by a new commit incorporating your
changes, giving you a chance to edit the old commit message first.
+This is useful for fixing typos in your last commit, or for adjusting
+the patch contents of a poorly staged commit.
-You can also use a combination of this and linkgit:git-rebase[1] to
-replace a commit further back in your history and recreate the
-intervening changes on top of it. First, tag the problematic commit
-with
-
--------------------------------------------------
-$ git tag bad mywork~5
--------------------------------------------------
+If you need to amend commits from deeper in your history, you can
+use <<interactive-rebase,interactive rebase's `edit` instruction>>.
-(Either gitk or `git log` may be useful for finding the commit.)
+[[reordering-patch-series]]
+Reordering or selecting from a patch series
+-------------------------------------------
-Then check out that commit, edit it, and rebase the rest of the series
-on top of it (note that we could check out the commit on a temporary
-branch, but instead we're using a <<detached-head,detached head>>):
+Sometimes you want to edit a commit deeper in your history. One
+approach is to use `git format-patch` to create a series of patches
+and then reset the state to before the patches:
-------------------------------------------------
-$ git checkout bad
-$ # make changes here and update the index
-$ git commit --amend
-$ git rebase --onto HEAD bad mywork
+$ git format-patch origin
+$ git reset --hard origin
-------------------------------------------------
-When you're done, you'll be left with mywork checked out, with the top
-patches on mywork reapplied on top of your modified commit. You can
-then clean up with
+Then modify, reorder, or eliminate patches as needed before applying
+them again with linkgit:git-am[1]:
-------------------------------------------------
-$ git tag -d bad
+$ git am *.patch
-------------------------------------------------
-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.
+[[interactive-rebase]]
+Using interactive rebases
+-------------------------
-[[reordering-patch-series]]
-Reordering or selecting from a patch series
--------------------------------------------
+You can also edit a patch series with an interactive rebase. This is
+the same as <<reordering-patch-series,reordering a patch series using
+`format-patch`>>, so use whichever interface you like best.
-Given one existing commit, the linkgit:git-cherry-pick[1] command
-allows you to apply the change introduced by that commit and create a
-new commit that records it. So, for example, if "mywork" points to a
-series of patches on top of "origin", you might do something like:
+Rebase your current HEAD on the last commit you want to retain as-is.
+For example, if you want to reorder the last 5 commits, use:
-------------------------------------------------
-$ git checkout -b mywork-new origin
-$ gitk origin..mywork &
+$ git rebase -i HEAD~5
-------------------------------------------------
-and browse through the list of patches in the mywork branch using gitk,
-applying them (possibly in a different order) to mywork-new using
-cherry-pick, and possibly modifying them as you go using `git commit --amend`.
-The linkgit:git-gui[1] command may also help as it allows you to
-individually select diff hunks for inclusion in the index (by
-right-clicking on the diff hunk and choosing "Stage Hunk for Commit").
-
-Another technique is to use `git format-patch` to create a series of
-patches, then reset the state to before the patches:
+This will open your editor with a list of steps to be taken to perform
+your rebase.
-------------------------------------------------
-$ git format-patch origin
-$ git reset --hard origin
--------------------------------------------------
+pick deadbee The oneline of this commit
+pick fa1afe1 The oneline of the next commit
+...
-Then modify, reorder, or eliminate patches as preferred before applying
-them again with linkgit:git-am[1].
+# Rebase c0ffeee..deadbee onto c0ffeee
+#
+# Commands:
+# p, pick = use commit
+# r, reword = use commit, but edit the commit message
+# e, edit = use commit, but stop for amending
+# s, squash = use commit, but meld into previous commit
+# f, fixup = like "squash", but discard this commit's log message
+# x, exec = run command (the rest of the line) using shell
+#
+# These lines can be re-ordered; they are executed from top to bottom.
+#
+# If you remove a line here THAT COMMIT WILL BE LOST.
+#
+# However, if you remove everything, the rebase will be aborted.
+#
+# Note that empty commits are commented out
+-------------------------------------------------
+
+As explained in the comments, you can reorder commits, squash them
+together, edit commit messages, etc. by editing the list. Once you
+are satisfied, save the list and close your editor, and the rebase
+will begin.
+
+The rebase will stop where `pick` has been replaced with `edit` or
+when a step in the list fails to mechanically resolve conflicts and
+needs your help. When you are done editing and/or resolving conflicts
+you can continue with `git rebase --continue`. If you decide that
+things are getting too hairy, you can always bail out with `git rebase
+--abort`. Even after the rebase is complete, you can still recover
+the original branch by using the <<reflogs,reflog>>.
+
+For a more detailed discussion of the procedure and additional tips,
+see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
[[patch-series-tools]]
Other tools
the old head; it treats this situation exactly the same as it would if
two developers had independently done the work on the old and new heads
in parallel. At this point, if someone attempts to merge the new head
-in to their branch, git will attempt to merge together the two (old and
+in to their branch, Git will attempt to merge together the two (old and
new) lines of development, instead of trying to replace the old by the
new. The results are likely to be unexpected.
Bisecting between Z and D* would hit a single culprit commit Y*,
and understanding why Y* was broken would probably be easier.
-Partly for this reason, many experienced git users, even when
+Partly for this reason, many experienced Git users, even when
working on an otherwise merge-heavy project, keep the history
linear by rebasing against the latest upstream version before
publishing.
$ git fetch origin todo:my-todo-work
-------------------------------------------------
-The first argument, "origin", just tells git to fetch from the
-repository you originally cloned from. The second argument tells git
+The first argument, "origin", just tells Git to fetch from the
+repository you originally cloned from. The second argument tells Git
to fetch the branch named "todo" from the remote repository, and to
store it locally under the name refs/heads/my-todo-work.
In this case, "git fetch" will fail, and print out a warning.
-In that case, you can still force git to update to the new head, as
+In that case, you can still force Git to update to the new head, as
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
We saw above that "origin" is just a shortcut to refer to the
repository that you originally cloned from. This information is
-stored in git configuration variables, which you can see using
+stored in Git configuration variables, which you can see using
linkgit:git-config[1]:
-------------------------------------------------
If there are other repositories that you also use frequently, you can
create similar configuration options to save typing; for example,
-after
-------------------------------------------------
-$ git config remote.example.url git://example.com/proj.git
+$ git remote add example git://example.com/proj.git
-------------------------------------------------
-then the following two commands will do the same thing:
+adds the following to `.git/config`:
-------------------------------------------------
-$ git fetch git://example.com/proj.git master:refs/remotes/example/master
-$ git fetch example master:refs/remotes/example/master
+[remote "example"]
+ url = git://example.com/proj.git
+ fetch = +refs/heads/*:refs/remotes/example/*
-------------------------------------------------
-Even better, if you add one more option:
+Also note that the above configuration can be performed by directly
+editing the file `.git/config` instead of using linkgit:git-remote[1].
--------------------------------------------------
-$ git config remote.example.fetch master:refs/remotes/example/master
--------------------------------------------------
-
-then the following commands will all do the same thing:
+After configuring the remote, the following three commands will do the
+same thing:
-------------------------------------------------
-$ git fetch git://example.com/proj.git master:refs/remotes/example/master
-$ git fetch example master:refs/remotes/example/master
+$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/*
+$ git fetch example +refs/heads/*:refs/remotes/example/*
$ git fetch example
-------------------------------------------------
-You can also add a "+" to force the update each time:
-
--------------------------------------------------
-$ git config remote.example.fetch +master:refs/remotes/example/master
--------------------------------------------------
-
-Don't do this unless you're sure you won't mind "git fetch" possibly
-throwing away commits on 'example/master'.
-
-Also note that all of the above configuration can be performed by
-directly editing the file .git/config instead of using
-linkgit:git-config[1].
-
See linkgit:git-config[1] for more details on the configuration
-options mentioned above.
+options mentioned above and linkgit:git-fetch[1] for more details on
+the refspec syntax.
[[git-concepts]]
Git 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.
+Git much more intuitive if you do.
We start with the most important, the <<def_object_database,object
database>> and the <<def_index,index>>.
Note that a commit does not itself contain any information about what
actually changed; all changes are calculated by comparing the contents
of the tree referred to by this commit with the trees associated with
-its parents. In particular, git does not attempt to record file renames
+its parents. In particular, Git does not attempt to record file renames
explicitly, though it can identify cases where the existence of the same
file data at changing paths suggests a rename. (See, for example, the
-M option to linkgit:git-diff[1]).
and blobs, like all other objects, are named by the SHA-1 hash of their
contents, two trees have the same SHA-1 name if and only if their
contents (including, recursively, the contents of all subdirectories)
-are identical. This allows git to quickly determine the differences
+are identical. This allows Git to quickly determine the differences
between two related tree objects, since it can ignore any entries with
identical object names.
(Note: in the presence of submodules, trees may also have commits as
entries. See <<submodules>> for documentation.)
-Note that the files all have mode 644 or 755: git actually only pays
+Note that the files all have mode 644 or 755: Git actually only pays
attention to the executable bit.
[[blob-object]]
of the top commit, and digitally sign that email using something
like GPG/PGP.
-To assist in this, git also provides the tag object...
+To assist in this, Git also provides the tag object...
[[tag-object]]
Tag Object
references whose names begin with "refs/tags/").
[[pack-files]]
-How git stores objects efficiently: pack files
+How Git stores objects efficiently: pack files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Newly created objects are initially created in a file named after the
individual files. The second is the amount of space taken up by
those "loose" objects.
-You can save space and make git faster by moving these loose objects in
+You can save space and make Git faster by moving these loose objects in
to a "pack file", which stores a group of objects in an efficient
compressed format; the details of how pack files are formatted can be
found in link:technical/pack-format.txt[technical/pack-format.txt].
Recovering from repository corruption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-By 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
+By 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
operating system errors could corrupt data.
The first defense against such problems is backups. You can back up a
-git directory using clone, or just using cp, tar, or any other backup
+Git directory using clone, or just using cp, tar, or any other backup
mechanism.
As a last resort, you can search for the corrupted objects and attempt
------------------------------------------------
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
+whole thing. It's up to you--Git does *have* a lot of information, it is
just missing one particular blob version.
[[the-index]]
the last modified time). This data is not displayed above, and is not
stored in the created tree object, but it can be used to determine
quickly which files in the working directory differ from what was
-stored in the index, and thus save git from having to read all of the
+stored in the index, and thus save Git from having to read all of the
data from such files to look for changes.
3. It can efficiently represent information about merge conflicts
Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
-------------------------------------------------
-In older git versions it could be easily forgotten to commit new or modified
+In older Git versions it could be easily forgotten to commit new or modified
files in a submodule, which silently leads to similar problems as not pushing
-the submodule changes. Starting with git 1.7.0 both "git status" and "git diff"
+the submodule changes. Starting with Git 1.7.0 both "git status" and "git diff"
in the superproject show submodules as modified when they contain new or
modified files to protect against accidentally committing such a state. "git
diff" will also add a "-dirty" to the work tree side when generating patch
NOTE: The changes are still visible in the submodule's reflog.
-This is not the case if you did not commit your changes.
+If you have uncommitted changes in your submodule working tree, `git
+submodule update` will not overwrite them. Instead, you get the usual
+warning about not being able switch from a dirty branch.
[[low-level-operations]]
-Low-level git operations
+Low-level Git operations
========================
Many 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
+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-manipulation]]
provides low-level operations which perform each of these steps
individually.
-Generally, all "git" operations work on the index file. Some operations
+Generally, all Git operations work on the index file. Some operations
work *purely* on the index file (showing the current state of the
index), but most operations move data between the index file and either
the database or the working directory. Thus there are four main
will not normally add totally new entries or remove old entries,
i.e. it will normally just update existing cache entries.
-To tell git that yes, you really do realize that certain files no
+To tell Git that yes, you really do realize that certain files no
longer exist, or that new files should be added, you
should use the `--remove` and `--add` flags respectively.
`git commit-tree` will return the name of the object that represents
that commit, and you should save it away for later use. Normally,
-you'd commit a new `HEAD` state, and while git doesn't care where you
+you'd commit a new `HEAD` state, and while Git doesn't care where you
save the note about that state, in practice we tend to just write the
result to the file pointed at by `.git/HEAD`, so that we can always see
what the last committed state was.
Each line of the `git ls-files --unmerged` output begins with
the blob mode bits, blob SHA-1, 'stage number', and the
-filename. The 'stage number' is git's way to say which tree it
+filename. The 'stage number' is Git's way to say which tree it
came from: stage 1 corresponds to the `$orig` tree, stage 2 to
the `HEAD` tree, and stage 3 to the `$target` tree.
above example shows is that file `hello.c` was changed from
`$orig` to `HEAD` and `$orig` to `$target` in a different way.
You could resolve this by running your favorite 3-way merge
-program, e.g. `diff3`, `merge`, or git's own merge-file, on
+program, e.g. `diff3`, `merge`, or Git's own merge-file, on
the blob objects from these three stages yourself, like this:
------------------------------------------------
This would leave the merge result in `hello.c~2` file, along
with conflict markers if there are conflicts. After verifying
-the merge result makes sense, you can tell git what the final
+the merge result makes sense, you can tell Git what the final
merge result for this file is by:
-------------------------------------------------
-------------------------------------------------
When a path is in the "unmerged" state, running `git update-index` for
-that path tells git to mark the path resolved.
+that path tells Git to mark the path resolved.
-The above is the description of a git merge at the lowest level,
+The above is the description of a Git merge at the lowest level,
to help you understand what conceptually happens under the hood.
-In practice, nobody, not even git itself, runs `git cat-file` three times
+In practice, nobody, not even Git itself, runs `git cat-file` three times
for this. There is a `git merge-index` program that extracts the
stages to temporary files and calls a "merge" script on it:
and that is what higher level `git merge -s resolve` is implemented with.
[[hacking-git]]
-Hacking git
+Hacking Git
===========
-This chapter covers internal details of the git implementation which
-probably only git developers need to understand.
+This chapter covers internal details of the Git implementation which
+probably only Git developers need to understand.
[[object-details]]
Object storage format
that is used to name the object is the hash of the original data
plus this header, so `sha1sum` 'file' does not match the object name
for 'file'.
-(Historical note: in the dawn of the age of git the hash
+(Historical note: in the dawn of the age of Git the hash
was the SHA-1 of the 'compressed' object.)
As a result, the general consistency of an object can always be tested
$ git checkout e83c5163
----------------------------------------------------
-The initial revision lays the foundation for almost everything git has
+The initial revision lays the foundation for almost everything Git has
today, but is small enough to read in one sitting.
Note that terminology has changed since that revision. For example, the
This is how you read a blob (actually, not only a blob, but any type of
object). To know how the function `read_object_with_reference()` actually
works, find the source code for it (something like `git grep
-read_object_with | grep ":[a-z]"` in the git repository), and read
+read_object_with | grep ":[a-z]"` in the Git repository), and read
the source.
To find out how the result can be used, just read on in `cmd_cat_file()`:
Making changes
--------------
-Make sure git knows who to blame:
+Make sure Git knows who to blame:
------------------------------------------------
$ cat >>~/.gitconfig <<\EOF
$ git am mbox # import patches from the mailbox "mbox"
-----------------------------------------------
-Fetch a branch in a different git repository, then merge into the
+Fetch a branch in a different Git repository, then merge into the
current branch:
-----------------------------------------------
- It must be readable in order, from beginning to end, by someone
intelligent with a basic grasp of the UNIX command line, but without
- any special knowledge of git. If necessary, any other prerequisites
+ any special knowledge of Git. If necessary, any other prerequisites
should be specifically mentioned as they arise.
- Whenever possible, section headings should clearly describe the task
they explain how to do, in language that requires no more knowledge