Merge branch 'maint'
* maint: Documentation: don't reference non-existent 'git-cvsapplycommit' user-manual: stop deprecating the manual user-manual: miscellaneous editing user-manual: fix .gitconfig editing examples user-manual: clean up fast-forward and dangling-objects sections user-manual: add section ID's user-manual: more discussion of detached heads, fix typos git-gui: Allow spaces in path to 'wish' gitk: Allow user to choose whether to see the diff, old file, or new file
This commit is contained in:
Junio C Hamano
commit
679c7c56ed
@ -25,7 +25,7 @@ by default.
|
||||
|
||||
Supports file additions, removals, and commits that affect binary files.
|
||||
|
||||
If the commit is a merge commit, you must tell git-cvsapplycommit what parent
|
||||
If the commit is a merge commit, you must tell git-cvsexportcommit what parent
|
||||
should the changeset be done against.
|
||||
|
||||
OPTIONS
|
||||
|
||||
@ -21,10 +21,9 @@ and full access to internals.
|
||||
See this link:tutorial.html[tutorial] to get started, then see
|
||||
link:everyday.html[Everyday Git] for a useful minimum set of commands, and
|
||||
"man git-commandname" for documentation of each command. CVS users may
|
||||
also want to read link:cvs-migration.html[CVS migration].
|
||||
link:user-manual.html[Git User's Manual] is still work in
|
||||
progress, but when finished hopefully it will guide a new user
|
||||
in a coherent way to git enlightenment ;-).
|
||||
also want to read link:cvs-migration.html[CVS migration]. See
|
||||
link:user-manual.html[Git User's Manual] for a more in-depth
|
||||
introduction.
|
||||
|
||||
The COMMAND is either a name of a Git command (see below) or an alias
|
||||
as defined in the configuration file (see gitlink:git-config[1]).
|
||||
|
||||
@ -23,12 +23,14 @@ pages. For a command such as "git clone", just use
|
||||
$ man git-clone
|
||||
------------------------------------------------
|
||||
|
||||
[[git-quick-start]]
|
||||
Git Quick Start
|
||||
===============
|
||||
|
||||
This is a quick summary of the major commands; the following chapters
|
||||
will explain how these work in more detail.
|
||||
|
||||
[[quick-creating-a-new-repository]]
|
||||
Creating a new repository
|
||||
-------------------------
|
||||
|
||||
@ -50,11 +52,12 @@ $ git clone git://example.com/pub/project.git
|
||||
$ cd project
|
||||
-----------------------------------------------
|
||||
|
||||
[[managing-branches]]
|
||||
Managing branches
|
||||
-----------------
|
||||
|
||||
-----------------------------------------------
|
||||
$ git branch # list all branches in this repo
|
||||
$ git branch # list all local branches in this repo
|
||||
$ git checkout test # switch working directory to branch "test"
|
||||
$ git branch new # create branch "new" starting at current HEAD
|
||||
$ git branch -d new # delete branch "new"
|
||||
@ -112,6 +115,7 @@ $ git branch -r # list all remote branches
|
||||
-----------------------------------------------
|
||||
|
||||
|
||||
[[exploring-history]]
|
||||
Exploring history
|
||||
-----------------
|
||||
|
||||
@ -147,13 +151,14 @@ $ git bisect bad # if this revision is bad.
|
||||
# repeat until done.
|
||||
-----------------------------------------------
|
||||
|
||||
[[making-changes]]
|
||||
Making changes
|
||||
--------------
|
||||
|
||||
Make sure git knows who to blame:
|
||||
|
||||
------------------------------------------------
|
||||
$ cat >~/.gitconfig <<\EOF
|
||||
$ cat >>~/.gitconfig <<\EOF
|
||||
[user]
|
||||
name = Your Name Comes Here
|
||||
email = you@yourdomain.example.com
|
||||
@ -177,6 +182,7 @@ $ git commit d.txt # use latest content only of d.txt
|
||||
$ git commit -a # use latest content of all tracked files
|
||||
-----------------------------------------------
|
||||
|
||||
[[merging]]
|
||||
Merging
|
||||
-------
|
||||
|
||||
@ -187,6 +193,7 @@ $ git pull git://example.com/project.git master
|
||||
$ git pull . test # equivalent to git merge test
|
||||
-----------------------------------------------
|
||||
|
||||
[[sharing-your-changes]]
|
||||
Sharing your changes
|
||||
--------------------
|
||||
|
||||
@ -232,6 +239,7 @@ $ git remote add example ssh://example.com/project.git
|
||||
$ git push example test
|
||||
-----------------------------------------------
|
||||
|
||||
[[repository-maintenance]]
|
||||
Repository maintenance
|
||||
----------------------
|
||||
|
||||
@ -247,9 +255,11 @@ Recompress, remove unused cruft:
|
||||
$ git gc
|
||||
-----------------------------------------------
|
||||
|
||||
[[repositories-and-branches]]
|
||||
Repositories and Branches
|
||||
=========================
|
||||
|
||||
[[how-to-get-a-git-repository]]
|
||||
How to get a git repository
|
||||
---------------------------
|
||||
|
||||
@ -280,6 +290,7 @@ contains all the information about the history of the project.
|
||||
In most of the following, examples will be taken from one of the two
|
||||
repositories above.
|
||||
|
||||
[[how-to-check-out]]
|
||||
How to check out a different version of a project
|
||||
-------------------------------------------------
|
||||
|
||||
@ -352,6 +363,7 @@ 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-commits]]
|
||||
Understanding History: Commits
|
||||
------------------------------
|
||||
|
||||
@ -407,6 +419,7 @@ In fact, in <<git-internals>> 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-reachability]]
|
||||
Understanding history: commits, parents, and reachability
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -431,6 +444,7 @@ if commit X is an ancestor of commit Y. Equivalently, you could say
|
||||
that Y is a descendent of X, or that there is a chain of parents
|
||||
leading from commit Y to commit X.
|
||||
|
||||
[[history-diagrams]]
|
||||
Understanding history: History diagrams
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -450,6 +464,7 @@ lines drawn with - / and \. Time goes left to right:
|
||||
If we need to talk about a particular commit, the character "o" may
|
||||
be replaced with another letter or number.
|
||||
|
||||
[[what-is-a-branch]]
|
||||
Understanding history: What is a branch?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -463,6 +478,7 @@ the line of three commits leading up to that point as all being part of
|
||||
However, when no confusion will result, we often just use the term
|
||||
"branch" both for branches and for branch heads.
|
||||
|
||||
[[manipulating-branches]]
|
||||
Manipulating branches
|
||||
---------------------
|
||||
|
||||
@ -480,8 +496,8 @@ git branch <branch> <start-point>::
|
||||
including using a branch name or a tag name
|
||||
git branch -d <branch>::
|
||||
delete the branch <branch>; if the branch you are deleting
|
||||
points to a commit which is not reachable from this branch,
|
||||
this command will fail with a warning.
|
||||
points to a commit which is not reachable from the current
|
||||
branch, this command will fail with a warning.
|
||||
git branch -D <branch>::
|
||||
even if the branch points to a commit not reachable
|
||||
from the current branch, you may know that that commit
|
||||
@ -527,18 +543,18 @@ and git branch shows that you are no longer on a branch:
|
||||
------------------------------------------------
|
||||
$ cat .git/HEAD
|
||||
427abfa28afedffadfca9dd8b067eb6d36bac53f
|
||||
git branch
|
||||
$ git branch
|
||||
* (no branch)
|
||||
master
|
||||
------------------------------------------------
|
||||
|
||||
In this case we say that the HEAD is "detached".
|
||||
|
||||
This can be an easy way to check out a particular version without having
|
||||
to make up a name for a new branch. However, keep in mind that when you
|
||||
switch away from the (for example, by checking out something else), you
|
||||
can lose track of what the HEAD used to point to.
|
||||
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-remote-branches]]
|
||||
Examining branches from a remote repository
|
||||
-------------------------------------------
|
||||
|
||||
@ -586,13 +602,9 @@ shorthand:
|
||||
The full name is occasionally useful if, for example, there ever
|
||||
exists a tag and a branch with the same name.
|
||||
|
||||
As another useful shortcut, if the repository "origin" posesses only
|
||||
a single branch, you can refer to that branch as just "origin".
|
||||
|
||||
More generally, if you have defined a remote repository named
|
||||
"example", you can refer to the branch in that repository as
|
||||
"example". And for a repository with multiple branches, this will
|
||||
refer to the branch designated as the "HEAD" branch.
|
||||
As another useful shortcut, the "HEAD" of a repository can be referred
|
||||
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
|
||||
the order it uses to decide which to choose when there are multiple
|
||||
@ -612,6 +624,7 @@ 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]]
|
||||
Fetching branches from other repositories
|
||||
-----------------------------------------
|
||||
|
||||
@ -654,6 +667,7 @@ or delete these configuration options by editing .git/config with a
|
||||
text editor. (See the "CONFIGURATION FILE" section of
|
||||
gitlink:git-config[1] for details.)
|
||||
|
||||
[[exploring-git-history]]
|
||||
Exploring git history
|
||||
=====================
|
||||
|
||||
@ -668,6 +682,7 @@ history of a project.
|
||||
We start with one specialized tool that is useful for finding the
|
||||
commit that introduced a bug into a project.
|
||||
|
||||
[[using-bisect]]
|
||||
How to use bisect to find a regression
|
||||
--------------------------------------
|
||||
|
||||
@ -735,6 +750,7 @@ $ git reset --hard fb47ddb2db...
|
||||
then test, run "bisect good" or "bisect bad" as appropriate, and
|
||||
continue.
|
||||
|
||||
[[naming-commits]]
|
||||
Naming commits
|
||||
--------------
|
||||
|
||||
@ -799,6 +815,7 @@ $ git rev-parse origin
|
||||
e05db0fd4f31dde7005f075a84f96b360d05984b
|
||||
-------------------------------------------------
|
||||
|
||||
[[creating-tags]]
|
||||
Creating tags
|
||||
-------------
|
||||
|
||||
@ -811,11 +828,12 @@ $ git tag stable-1 1b2e1d63ff
|
||||
|
||||
You can use stable-1 to refer to the commit 1b2e1d63ff.
|
||||
|
||||
This creates a "lightweight" tag. If the tag is a tag you wish to
|
||||
share with others, and possibly sign cryptographically, then you
|
||||
should create a tag object instead; see the gitlink:git-tag[1] man
|
||||
page for details.
|
||||
This creates a "lightweight" tag. If you would also like to include a
|
||||
comment with the tag, and possibly sign it cryptographically, then you
|
||||
should create a tag object instead; see the gitlink:git-tag[1] man page
|
||||
for details.
|
||||
|
||||
[[browsing-revisions]]
|
||||
Browsing revisions
|
||||
------------------
|
||||
|
||||
@ -857,6 +875,7 @@ 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-diffs]]
|
||||
Generating diffs
|
||||
----------------
|
||||
|
||||
@ -878,6 +897,7 @@ but not from master. Note that if master also has commits which are
|
||||
not reachable from test, then the combined result of these patches
|
||||
will not be the same as the diff produced by the git-diff example.
|
||||
|
||||
[[viewing-old-file-versions]]
|
||||
Viewing old file versions
|
||||
-------------------------
|
||||
|
||||
@ -893,9 +913,11 @@ $ git show v2.5:fs/locks.c
|
||||
Before the colon may be anything that names a commit, and after it
|
||||
may be any path to a file tracked by git.
|
||||
|
||||
[[history-examples]]
|
||||
Examples
|
||||
--------
|
||||
|
||||
[[checking-for-equal-branches]]
|
||||
Check whether two branches point at the same history
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -928,6 +950,7 @@ $ git log origin...master
|
||||
|
||||
will return no commits when the two branches are equal.
|
||||
|
||||
[[finding-tagged-descendants]]
|
||||
Find first tagged version including a given fix
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -1013,27 +1036,29 @@ 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.
|
||||
|
||||
|
||||
[[Developing-with-git]]
|
||||
Developing with git
|
||||
===================
|
||||
|
||||
[[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:
|
||||
easiest way to do so is to make sure the following lines appear in a
|
||||
file named .gitconfig in your home directory:
|
||||
|
||||
------------------------------------------------
|
||||
$ cat >~/.gitconfig <<\EOF
|
||||
[user]
|
||||
name = Your Name Comes Here
|
||||
email = you@yourdomain.example.com
|
||||
EOF
|
||||
------------------------------------------------
|
||||
|
||||
(See the "CONFIGURATION FILE" section of gitlink:git-config[1] for
|
||||
details on the configuration file.)
|
||||
|
||||
|
||||
[[creating-a-new-repository]]
|
||||
Creating a new repository
|
||||
-------------------------
|
||||
|
||||
@ -1147,9 +1172,12 @@ $ git diff --cached # difference between HEAD and the index; what
|
||||
$ git diff # difference between the index file and your
|
||||
# working directory; changes that would not
|
||||
# be included if you ran "commit" now.
|
||||
$ git diff HEAD # difference between HEAD and working tree; what
|
||||
# would be committed if you ran "commit -a" now.
|
||||
$ git status # a brief per-file summary of the above.
|
||||
-------------------------------------------------
|
||||
|
||||
[[creating-good-commit-messages]]
|
||||
Creating good commit messages
|
||||
-----------------------------
|
||||
|
||||
@ -1160,6 +1188,7 @@ 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.
|
||||
|
||||
[[how-to-merge]]
|
||||
How to merge
|
||||
------------
|
||||
|
||||
@ -1192,8 +1221,6 @@ 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.
|
||||
|
||||
In more detail:
|
||||
|
||||
[[resolving-a-merge]]
|
||||
Resolving a merge
|
||||
-----------------
|
||||
@ -1237,6 +1264,7 @@ 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:
|
||||
|
||||
[[conflict-resolution]]
|
||||
Getting conflict-resolution help during a merge
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -1329,6 +1357,9 @@ $ gitk --merge
|
||||
These will display all commits which exist only on HEAD or on
|
||||
MERGE_HEAD, and which touch an unmerged file.
|
||||
|
||||
You may also use gitlink:git-mergetool, which lets you merge the
|
||||
unmerged files using external tools such as emacs or kdiff3.
|
||||
|
||||
Each time you resolve the conflicts in a file and update the index:
|
||||
|
||||
-------------------------------------------------
|
||||
@ -1360,6 +1391,7 @@ 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-forwards]]
|
||||
Fast-forward merges
|
||||
-------------------
|
||||
|
||||
@ -1368,13 +1400,13 @@ differently. Normally, a merge results in a merge commit, with two
|
||||
parents, one pointing at each of the two lines of development that
|
||||
were merged.
|
||||
|
||||
However, if one of the two lines of development is completely
|
||||
contained within the other--so every commit present in the one is
|
||||
already contained in the other--then git just performs a
|
||||
<<fast-forwards,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.
|
||||
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
|
||||
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-mistakes]]
|
||||
Fixing mistakes
|
||||
---------------
|
||||
|
||||
@ -1399,6 +1431,7 @@ fundamentally different ways to fix the problem:
|
||||
change, and cannot correctly perform repeated merges from
|
||||
a branch that has had its history changed.
|
||||
|
||||
[[reverting-a-commit]]
|
||||
Fixing a mistake with a new commit
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -1453,6 +1486,7 @@ It is also possible to edit commits further back in the history, but
|
||||
this is an advanced topic to be left for
|
||||
<<cleaning-up-history,another chapter>>.
|
||||
|
||||
[[checkout-of-path]]
|
||||
Checking out an old version of a file
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -1479,6 +1513,7 @@ $ git show HEAD^:path/to/file
|
||||
|
||||
which will display the given version of the file.
|
||||
|
||||
[[ensuring-good-performance]]
|
||||
Ensuring good performance
|
||||
-------------------------
|
||||
|
||||
@ -1495,9 +1530,12 @@ $ 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.
|
||||
|
||||
|
||||
[[ensuring-reliability]]
|
||||
Ensuring reliability
|
||||
--------------------
|
||||
|
||||
[[checking-for-corruption]]
|
||||
Checking the repository for corruption
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -1518,8 +1556,10 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
|
||||
...
|
||||
-------------------------------------------------
|
||||
|
||||
Dangling objects are objects that are harmless, but also unnecessary;
|
||||
you can remove them at any time with gitlink:git-prune[1] or the --prune
|
||||
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 of
|
||||
recovery lost work--see <<dangling-objects>> for details. However, if
|
||||
you want, you may remove them with gitlink:git-prune[1] or the --prune
|
||||
option to gitlink:git-gc[1]:
|
||||
|
||||
-------------------------------------------------
|
||||
@ -1530,12 +1570,11 @@ This may be time-consuming. Unlike most other git operations (including
|
||||
git-gc when run without any options), it is not safe to prune while
|
||||
other git operations are in progress in the same repository.
|
||||
|
||||
For more about dangling objects, see <<dangling-objects>>.
|
||||
|
||||
|
||||
[[recovering-lost-changes]]
|
||||
Recovering lost changes
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
[[reflogs]]
|
||||
Reflogs
|
||||
^^^^^^^
|
||||
|
||||
@ -1560,8 +1599,19 @@ $ git show master@{2} # See where the branch pointed 2,
|
||||
$ git show master@{3} # 3, ... changes ago.
|
||||
$ gitk master@{yesterday} # See where it pointed yesterday,
|
||||
$ gitk master@{"1 week ago"} # ... or last week
|
||||
$ git log --walk-reflogs master # show reflog entries for master
|
||||
-------------------------------------------------
|
||||
|
||||
A separate reflog is kept for the HEAD, so
|
||||
|
||||
-------------------------------------------------
|
||||
$ git show HEAD@{"1 week ago"}
|
||||
-------------------------------------------------
|
||||
|
||||
will show what HEAD pointed to one week ago, not what the current branch
|
||||
pointed to one week ago. This allows you to see the history of what
|
||||
you've checked out.
|
||||
|
||||
The reflogs are kept by default for 30 days, after which they may be
|
||||
pruned. See gitlink:git-reflog[1] and gitlink:git-gc[1] to learn
|
||||
how to control this pruning, and see the "SPECIFYING REVISIONS"
|
||||
@ -1572,15 +1622,16 @@ 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.
|
||||
|
||||
[[dangling-object-recovery]]
|
||||
Examining dangling objects
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In 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 contained. The reflog is also deleted; however, if you have not
|
||||
yet pruned the repository, then you may still be able to find
|
||||
the lost commits; run git-fsck and watch for output that mentions
|
||||
"dangling commits":
|
||||
In 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
|
||||
contained. The reflog is also deleted; however, if you have not yet
|
||||
pruned the repository, then you may still be able to find the lost
|
||||
commits in the dangling objects that git-fsck reports. See
|
||||
<<dangling-objects>> for the details.
|
||||
|
||||
-------------------------------------------------
|
||||
$ git fsck
|
||||
@ -1612,7 +1663,11 @@ reference pointing to it, for example, a new branch:
|
||||
$ git branch recovered-branch 7281251ddd
|
||||
------------------------------------------------
|
||||
|
||||
Other types of dangling objects (blobs and trees) are also possible, and
|
||||
dangling objects can arise in other situations.
|
||||
|
||||
|
||||
[[sharing-development]]
|
||||
Sharing development with others
|
||||
===============================
|
||||
|
||||
@ -1649,9 +1704,16 @@ so often you can accomplish the above with just
|
||||
$ git pull
|
||||
-------------------------------------------------
|
||||
|
||||
See the descriptions of the branch.<name>.remote and
|
||||
branch.<name>.merge options in gitlink:git-config[1] to learn
|
||||
how to control these defaults depending on the current branch.
|
||||
See the descriptions of the branch.<name>.remote and branch.<name>.merge
|
||||
options in gitlink:git-config[1] to learn how to control these defaults
|
||||
depending on the current branch. Also note that the --track option to
|
||||
gitlink:git-branch[1] and gitlink:git-checkout[1] can be used to
|
||||
automatically set the default remote branch to pull from at the time
|
||||
that a branch is created:
|
||||
|
||||
-------------------------------------------------
|
||||
$ git checkout --track -b origin/maint maint
|
||||
-------------------------------------------------
|
||||
|
||||
In addition to saving you keystrokes, "git pull" also helps you by
|
||||
producing a default commit message documenting the branch and
|
||||
@ -1672,6 +1734,7 @@ $ git merge branch
|
||||
|
||||
are roughly equivalent. The former is actually very commonly used.
|
||||
|
||||
[[submitting-patches]]
|
||||
Submitting patches to a project
|
||||
-------------------------------
|
||||
|
||||
@ -1693,6 +1756,7 @@ use the gitlink: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]]
|
||||
Importing patches to a project
|
||||
------------------------------
|
||||
|
||||
@ -1772,14 +1836,14 @@ Now, assume your personal repository is in the directory ~/proj. We
|
||||
first create a new clone of the repository:
|
||||
|
||||
-------------------------------------------------
|
||||
$ git clone --bare proj-clone.git
|
||||
$ git clone --bare proj.git
|
||||
-------------------------------------------------
|
||||
|
||||
The resulting directory proj-clone.git will contains a "bare" git
|
||||
The resulting directory proj.git will contains a "bare" git
|
||||
repository--it is just the contents of the ".git" directory, without
|
||||
a checked-out copy of a working directory.
|
||||
|
||||
Next, copy proj-clone.git to the server where you plan to host the
|
||||
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.
|
||||
|
||||
@ -1805,7 +1869,7 @@ adjustments to give web clients some extra information they need:
|
||||
-------------------------------------------------
|
||||
$ mv proj.git /home/you/public_html/proj.git
|
||||
$ cd proj.git
|
||||
$ git update-server-info
|
||||
$ git --bare update-server-info
|
||||
$ chmod a+x hooks/post-update
|
||||
-------------------------------------------------
|
||||
|
||||
@ -1872,7 +1936,7 @@ As with git-fetch, you may also set up configuration options to
|
||||
save typing; so, for example, after
|
||||
|
||||
-------------------------------------------------
|
||||
$ cat >.git/config <<EOF
|
||||
$ cat >>.git/config <<EOF
|
||||
[remote "public-repo"]
|
||||
url = ssh://yourserver.com/~you/proj.git
|
||||
EOF
|
||||
@ -1888,6 +1952,7 @@ See the explanations of the remote.<name>.url, branch.<name>.remote,
|
||||
and remote.<name>.push options in gitlink:git-config[1] for
|
||||
details.
|
||||
|
||||
[[setting-up-a-shared-repository]]
|
||||
Setting up a shared repository
|
||||
------------------------------
|
||||
|
||||
@ -1897,6 +1962,7 @@ all push to and pull from a single shared repository. See
|
||||
link:cvs-migration.txt[git for CVS users] for instructions on how to
|
||||
set this up.
|
||||
|
||||
[[setting-up-gitweb]]
|
||||
Allow web browsing of a repository
|
||||
----------------------------------
|
||||
|
||||
@ -1904,6 +1970,7 @@ 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.
|
||||
|
||||
[[sharing-development-examples]]
|
||||
Examples
|
||||
--------
|
||||
|
||||
@ -1921,6 +1988,7 @@ 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.
|
||||
|
||||
[[patch-series]]
|
||||
Creating the perfect patch series
|
||||
---------------------------------
|
||||
|
||||
@ -1953,6 +2021,7 @@ 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.
|
||||
|
||||
[[using-git-rebase]]
|
||||
Keeping a patch series up to date using git-rebase
|
||||
--------------------------------------------------
|
||||
|
||||
@ -2034,6 +2103,7 @@ return mywork to the state it had before you started the rebase:
|
||||
$ git rebase --abort
|
||||
-------------------------------------------------
|
||||
|
||||
[[modifying-one-commit]]
|
||||
Modifying a single commit
|
||||
-------------------------
|
||||
|
||||
@ -2079,6 +2149,7 @@ 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-patch-series]]
|
||||
Reordering or selecting from a patch series
|
||||
-------------------------------------------
|
||||
|
||||
@ -2108,6 +2179,7 @@ $ git reset --hard origin
|
||||
Then modify, reorder, or eliminate patches as preferred before applying
|
||||
them again with gitlink:git-am[1].
|
||||
|
||||
[[patch-series-tools]]
|
||||
Other tools
|
||||
-----------
|
||||
|
||||
@ -2115,6 +2187,7 @@ There 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-history]]
|
||||
Problems with rewriting history
|
||||
-------------------------------
|
||||
|
||||
@ -2163,9 +2236,11 @@ branches into their own work.
|
||||
For true distributed development that supports proper merging,
|
||||
published branches should never be rewritten.
|
||||
|
||||
[[advanced-branch-management]]
|
||||
Advanced branch management
|
||||
==========================
|
||||
|
||||
[[fetching-individual-branches]]
|
||||
Fetching individual branches
|
||||
----------------------------
|
||||
|
||||
@ -2191,18 +2266,18 @@ $ git fetch git://example.com/proj.git master:example-master
|
||||
will create a new branch named "example-master" and store in it the
|
||||
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. So
|
||||
next we explain what a fast-forward is:
|
||||
<<fast-forwards,fast-forward>> to the commit given by example.com's
|
||||
master branch. In more detail:
|
||||
|
||||
[[fast-forwards]]
|
||||
Understanding git history: fast-forwards
|
||||
----------------------------------------
|
||||
[[fetch-fast-forwards]]
|
||||
git fetch and fast-forwards
|
||||
---------------------------
|
||||
|
||||
In the previous example, when updating an existing branch, "git
|
||||
fetch" checks to make sure that the most recent commit on the remote
|
||||
branch is a descendant of the most recent commit on your copy of the
|
||||
branch before updating your copy of the branch to point at the new
|
||||
commit. Git calls this process a "fast forward".
|
||||
commit. Git calls this process a <<fast-forwards,fast forward>>.
|
||||
|
||||
A fast forward looks something like this:
|
||||
|
||||
@ -2232,6 +2307,7 @@ 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-fetch]]
|
||||
Forcing git fetch to do non-fast-forward updates
|
||||
------------------------------------------------
|
||||
|
||||
@ -2242,10 +2318,17 @@ descendant of the old head, you may force the update with:
|
||||
$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
|
||||
-------------------------------------------------
|
||||
|
||||
Note the addition of the "+" sign. Be aware that commits that the
|
||||
old version of example/master pointed at may be lost, as we saw in
|
||||
the previous section.
|
||||
Note the addition of the "+" sign. Alternatively, you can use the "-f"
|
||||
flag to force updates of all the fetched branches, as in:
|
||||
|
||||
-------------------------------------------------
|
||||
$ git fetch -f origin
|
||||
-------------------------------------------------
|
||||
|
||||
Be aware that commits that the old version of example/master pointed at
|
||||
may be lost, as we saw in the previous section.
|
||||
|
||||
[[remote-branch-configuration]]
|
||||
Configuring remote branches
|
||||
---------------------------
|
||||
|
||||
@ -2319,6 +2402,7 @@ Git internals
|
||||
Git depends on two fundamental abstractions: the "object database", and
|
||||
the "current directory cache" aka "index".
|
||||
|
||||
[[the-object-database]]
|
||||
The Object Database
|
||||
-------------------
|
||||
|
||||
@ -2328,7 +2412,7 @@ approximated by the SHA1 hash of the object itself. Objects may refer
|
||||
to other objects (by referencing their SHA1 hash), and so you can
|
||||
build up a hierarchy of objects.
|
||||
|
||||
All objects have a statically determined "type" aka "tag", which is
|
||||
All objects have a statically determined "type" which is
|
||||
determined at object creation time, and which identifies the format of
|
||||
the object (i.e. how it is used, and how it can refer to other
|
||||
objects). There are currently four different object types: "blob",
|
||||
@ -2351,7 +2435,7 @@ the time of the commit). In addition, a "commit" refers to one or more
|
||||
that directory hierarchy.
|
||||
|
||||
As a special case, a commit object with no parents is called the "root"
|
||||
object, and is the point of an initial project commit. Each project
|
||||
commit, and is the point of an initial project commit. Each project
|
||||
must have at least one root, and while you can tie several different
|
||||
root objects together into one project by creating a commit object which
|
||||
has two or more separate roots as its ultimate parents, that's probably
|
||||
@ -2388,6 +2472,7 @@ to just verifying their superficial consistency through the hash).
|
||||
|
||||
The object types in some more detail:
|
||||
|
||||
[[blob-object]]
|
||||
Blob Object
|
||||
-----------
|
||||
|
||||
@ -2409,6 +2494,7 @@ file is associated with in any way.
|
||||
A blob is typically created when gitlink:git-update-index[1]
|
||||
is run, and its data can be accessed by gitlink:git-cat-file[1].
|
||||
|
||||
[[tree-object]]
|
||||
Tree Object
|
||||
-----------
|
||||
|
||||
@ -2450,6 +2536,7 @@ A tree is created with gitlink:git-write-tree[1] and
|
||||
its data can be accessed by gitlink:git-ls-tree[1].
|
||||
Two trees can be compared with gitlink:git-diff-tree[1].
|
||||
|
||||
[[commit-object]]
|
||||
Commit Object
|
||||
-------------
|
||||
|
||||
@ -2467,7 +2554,7 @@ that the tree is "good" or that the merge information makes sense.
|
||||
The parents do not have to actually have any relationship with the
|
||||
result, for example.
|
||||
|
||||
Note on commits: unlike real SCM's, commits do not contain
|
||||
Note on commits: unlike some SCM's, commits do not contain
|
||||
rename information or file mode change information. All of that is
|
||||
implicit in the trees involved (the result tree, and the result trees
|
||||
of the parents), and describing that makes no sense in this idiotic
|
||||
@ -2476,6 +2563,7 @@ file manager.
|
||||
A commit is created with gitlink:git-commit-tree[1] and
|
||||
its data can be accessed by gitlink:git-cat-file[1].
|
||||
|
||||
[[trust]]
|
||||
Trust
|
||||
-----
|
||||
|
||||
@ -2505,6 +2593,7 @@ like GPG/PGP.
|
||||
|
||||
To assist in this, git also provides the tag object...
|
||||
|
||||
[[tag-object]]
|
||||
Tag Object
|
||||
----------
|
||||
|
||||
@ -2527,11 +2616,12 @@ and the signature can be verified by
|
||||
gitlink:git-verify-tag[1].
|
||||
|
||||
|
||||
[[the-index]]
|
||||
The "index" aka "Current Directory Cache"
|
||||
-----------------------------------------
|
||||
|
||||
The index is a simple binary file, which contains an efficient
|
||||
representation of a virtual directory content at some random time. It
|
||||
representation of the contents of a virtual directory. It
|
||||
does so by a simple array that associates a set of names, dates,
|
||||
permissions and content (aka "blob") objects together. The cache is
|
||||
always kept ordered by name, and names are unique (with a few very
|
||||
@ -2581,6 +2671,7 @@ been written back to the backing store.
|
||||
|
||||
|
||||
|
||||
[[the-workflow]]
|
||||
The Workflow
|
||||
------------
|
||||
|
||||
@ -2590,6 +2681,7 @@ index), but most operations move data to and from the index file. Either
|
||||
from the database or from the working directory. Thus there are four
|
||||
main combinations:
|
||||
|
||||
[[working-directory-to-index]]
|
||||
working directory -> index
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -2623,6 +2715,7 @@ stat information. It will 'not' update the object status itself, and
|
||||
it will only update the fields that are used to quickly test whether
|
||||
an object still matches its old backing store object.
|
||||
|
||||
[[index-to-object-database]]
|
||||
index -> object database
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -2638,6 +2731,7 @@ 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-to-index]]
|
||||
object database -> index
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -2654,6 +2748,7 @@ and 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-to-working-directory]]
|
||||
index -> working directory
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -2683,6 +2778,7 @@ need to use the "-f" flag ('before' the "-a" flag or the filename) to
|
||||
Finally, there are a few odds and ends which are not purely moving
|
||||
from one representation to the other:
|
||||
|
||||
[[tying-it-all-together]]
|
||||
Tying it all together
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -2758,6 +2854,7 @@ various pieces fit together.
|
||||
------------
|
||||
|
||||
|
||||
[[examining-the-data]]
|
||||
Examining the data
|
||||
------------------
|
||||
|
||||
@ -2793,6 +2890,7 @@ $ git-cat-file commit HEAD
|
||||
|
||||
to see what the top commit was.
|
||||
|
||||
[[merging-multiple-trees]]
|
||||
Merging multiple trees
|
||||
----------------------
|
||||
|
||||
@ -2826,7 +2924,7 @@ since the tree object information is always the first line in a commit
|
||||
object.
|
||||
|
||||
Once you know the three trees you are going to merge (the one "original"
|
||||
tree, aka the common case, and the two "result" trees, aka the branches
|
||||
tree, aka the common tree, and the two "result" trees, aka the branches
|
||||
you want to merge), you do a "merge" read into the index. This will
|
||||
complain if it has to throw away your old index contents, so you should
|
||||
make sure that you've committed those - in fact you would normally
|
||||
@ -2844,6 +2942,7 @@ index file, and you can just write the result out with
|
||||
`git-write-tree`.
|
||||
|
||||
|
||||
[[merging-multiple-trees-2]]
|
||||
Merging multiple trees, continued
|
||||
---------------------------------
|
||||
|
||||
@ -2879,14 +2978,14 @@ obviously the final outcome is what is in `HEAD`. What the
|
||||
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` or `merge`, on the blob objects from
|
||||
these three stages yourself, like this:
|
||||
program, e.g. `diff3`, `merge`, or git's own merge-file, on
|
||||
the blob objects from these three stages yourself, like this:
|
||||
|
||||
------------------------------------------------
|
||||
$ git-cat-file blob 263414f... >hello.c~1
|
||||
$ git-cat-file blob 06fa6a2... >hello.c~2
|
||||
$ git-cat-file blob cc44c73... >hello.c~3
|
||||
$ merge hello.c~2 hello.c~1 hello.c~3
|
||||
$ git merge-file hello.c~2 hello.c~1 hello.c~3
|
||||
------------------------------------------------
|
||||
|
||||
This would leave the merge result in `hello.c~2` file, along
|
||||
@ -2914,6 +3013,7 @@ $ git-merge-index git-merge-one-file hello.c
|
||||
|
||||
and that is what higher level `git merge -s resolve` is implemented with.
|
||||
|
||||
[[pack-files]]
|
||||
How git stores objects efficiently: pack files
|
||||
----------------------------------------------
|
||||
|
||||
@ -2984,11 +3084,10 @@ objects. They are not a problem.
|
||||
The most common cause of dangling objects is that you've rebased a
|
||||
branch, or you have pulled from somebody else who rebased a branch--see
|
||||
<<cleaning-up-history>>. In that case, the old head of the original
|
||||
branch still exists, as does obviously everything it pointed to. The
|
||||
branch pointer itself just doesn't, since you replaced it with another
|
||||
one.
|
||||
branch still exists, as does everything it pointed to. The branch
|
||||
pointer itself just doesn't, since you replaced it with another one.
|
||||
|
||||
There are also other situations too that cause dangling objects. For
|
||||
There are also other situations that cause dangling objects. For
|
||||
example, a "dangling blob" may arise because you did a "git add" of a
|
||||
file, but then, before you actually committed it and made it part of the
|
||||
bigger picture, you changed something else in that file and committed
|
||||
@ -3010,15 +3109,22 @@ be how you recover your old tree (say, you did a rebase, and realized
|
||||
that you really didn't want to - you can look at what dangling objects
|
||||
you have, and decide to reset your head to some old dangling state).
|
||||
|
||||
For commits, the most useful thing to do with dangling objects tends to
|
||||
be to do a simple
|
||||
For commits, you can just use:
|
||||
|
||||
------------------------------------------------
|
||||
$ gitk <dangling-commit-sha-goes-here> --not --all
|
||||
------------------------------------------------
|
||||
|
||||
For blobs and trees, you can't do the same, but you can examine them.
|
||||
You can just do
|
||||
This asks for all the history reachable from the given commit but not
|
||||
from any branch, tag, or other reference. If you decide it's something
|
||||
you want, you can always create a new reference to it, e.g.,
|
||||
|
||||
------------------------------------------------
|
||||
$ git branch recovered-branch <dangling-commit-sha-goes-here>
|
||||
------------------------------------------------
|
||||
|
||||
For blobs and trees, you can't do the same, but you can still examine
|
||||
them. You can just do
|
||||
|
||||
------------------------------------------------
|
||||
$ git show <dangling-blob/tree-sha-goes-here>
|
||||
@ -3055,8 +3161,10 @@ 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).
|
||||
|
||||
[[glossary]]
|
||||
include::glossary.txt[]
|
||||
|
||||
[[todo]]
|
||||
Notes and todo list for this manual
|
||||
===================================
|
||||
|
||||
|
||||
@ -4137,7 +4137,7 @@ proc do_gitk {revs} {
|
||||
# -- Always start gitk through whatever we were loaded with. This
|
||||
# lets us bypass using shell process on Windows systems.
|
||||
#
|
||||
set cmd [info nameofexecutable]
|
||||
set cmd [list [info nameofexecutable]]
|
||||
lappend cmd [gitexec gitk]
|
||||
if {$revs ne {}} {
|
||||
append cmd { }
|
||||
|
||||
17
gitk
17
gitk
@ -593,6 +593,7 @@ proc makewindow {} {
|
||||
frame .bleft -width $geometry(botwidth) -height $geometry(botheight)
|
||||
}
|
||||
frame .bleft.top
|
||||
frame .bleft.mid
|
||||
|
||||
button .bleft.top.search -text "Search" -command dosearch \
|
||||
-font $uifont
|
||||
@ -602,12 +603,20 @@ proc makewindow {} {
|
||||
lappend entries $sstring
|
||||
trace add variable searchstring write incrsearch
|
||||
pack $sstring -side left -expand 1 -fill x
|
||||
radiobutton .bleft.mid.diff -text "Diff" \
|
||||
-command changediffdisp -variable diffelide -value {0 0}
|
||||
radiobutton .bleft.mid.old -text "Old version" \
|
||||
-command changediffdisp -variable diffelide -value {0 1}
|
||||
radiobutton .bleft.mid.new -text "New version" \
|
||||
-command changediffdisp -variable diffelide -value {1 0}
|
||||
pack .bleft.mid.diff .bleft.mid.old .bleft.mid.new -side left
|
||||
set ctext .bleft.ctext
|
||||
text $ctext -background $bgcolor -foreground $fgcolor \
|
||||
-state disabled -font $textfont \
|
||||
-yscrollcommand scrolltext -wrap none
|
||||
scrollbar .bleft.sb -command "$ctext yview"
|
||||
pack .bleft.top -side top -fill x
|
||||
pack .bleft.mid -side top -fill x
|
||||
pack .bleft.sb -side right -fill y
|
||||
pack $ctext -side left -fill both -expand 1
|
||||
lappend bglist $ctext
|
||||
@ -4486,6 +4495,13 @@ proc getblobdiffline {bdf ids} {
|
||||
}
|
||||
}
|
||||
|
||||
proc changediffdisp {} {
|
||||
global ctext diffelide
|
||||
|
||||
$ctext tag conf d0 -elide [lindex $diffelide 0]
|
||||
$ctext tag conf d1 -elide [lindex $diffelide 1]
|
||||
}
|
||||
|
||||
proc prevfile {} {
|
||||
global difffilestart ctext
|
||||
set prev [lindex $difffilestart 0]
|
||||
@ -6330,6 +6346,7 @@ set highlight_paths {}
|
||||
set searchdirn -forwards
|
||||
set boldrows {}
|
||||
set boldnamerows {}
|
||||
set diffelide {0 0}
|
||||
|
||||
set optim_delay 16
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user