See also <<git-quick-start>> for a brief overview of git commands,
without any explanation.
-Also, see <<todo>> for ways that you can help make this manual more
+Finally, see <<todo>> for ways that you can help make this manual more
complete.
commits reachable from some head but not from any tag in the repository:
-------------------------------------------------
-$ gitk ($ git show-ref --heads ) --not $( git show-ref --tags )
+$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )
-------------------------------------------------
(See gitlink:git-rev-parse[1] for explanations of commit-selecting
and then he just cut-and-pastes the output commands after verifying that
they look OK.
+[[Finding-comments-with-given-content]]
+Finding commits referencing a file with given content
+-----------------------------------------------------
+
+Somebody hands you a copy of a file, and asks which commits modified a
+file such that it contained the given content either before or after the
+commit. You can find out with this:
+
+-------------------------------------------------
+$ git log --raw -r --abbrev=40 --pretty=oneline -- filename |
+ grep -B 1 `git hash-object filename`
+-------------------------------------------------
+
+Figuring out why this works is left as an exercise to the (advanced)
+student. The gitlink:git-log[1], gitlink:git-diff-tree[1], and
+gitlink:git-hash-object[1] man pages may prove helpful.
+
[[Developing-with-git]]
Developing with git
===================
the first line on the Subject line and the rest of the commit in the
body.
+[[ignoring-files]]
+Ignoring files
+--------------
+
+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
+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 .`" and "`git commit -a`" practically useless, and they keep
+showing up in the output of "`git status`", etc.
+
+Git therefore provides "exclude patterns" for telling git which files to
+actively ignore. Exclude patterns are thoroughly explained in the
+gitlink:gitignore[5] manual page, but the heart of the concept is simply
+a list of files which git should ignore. Entries in the list may contain
+globs to specify multiple files, or may be prefixed by "`!`" to
+explicitly include (un-ignore) a previously excluded (ignored) file
+(i.e. later exclude patterns override earlier ones). The following
+example should illustrate such patterns:
+
+-------------------------------------------------
+# Lines starting with '#' are considered comments.
+# Ignore foo.txt.
+foo.txt
+# Ignore (generated) html files,
+*.html
+# except foo.html which is maintained by hand.
+!foo.html
+# Ignore objects and archives.
+*.[oa]
+-------------------------------------------------
+
+The next question is where to put these exclude patterns so that git can
+find them. Git looks for exclude patterns in the following files:
+
+`.gitignore` files in your working tree:::
+ You may store multiple `.gitignore` files at various locations in your
+ working tree. Each `.gitignore` file is applied to the directory where
+ it's located, including its subdirectories. Furthermore, the
+ `.gitignore` files can be tracked like any other files in your working
+ tree; just do a "`git add .gitignore`" and commit. `.gitignore` is
+ therefore the right place to put exclude patterns that are meant to
+ be shared between all project participants, such as build output files
+ (e.g. `\*.o`), etc.
+`.git/info/exclude` in your repo:::
+ Exclude patterns in this file are applied to the working tree as a
+ whole. Since the file is not located in your working tree, it does
+ not follow push/pull/clone like `.gitignore` can do. This is therefore
+ the place to put exclude patterns that are local to your copy of the
+ repo (i.e. 'not' shared between project participants), such as
+ temporary backup files made by your editor (e.g. `\*~`), etc.
+The file specified by the `core.excludesfile` config directive:::
+ By setting the `core.excludesfile` config directive you can tell git
+ where to find more exclude patterns (see gitlink:git-config[1] for
+ more information on configuration options). This config directive
+ can be set in the per-repo `.git/config` file, in which case the
+ exclude patterns will apply to that repo only. Alternatively, you
+ can set the directive in the global `~/.gitconfig` file to apply
+ the exclude pattern to all your git repos. As with the above
+ `.git/info/exclude` (and, indeed, with git config directives in
+ general), this directive does not follow push/pull/clone, but remain
+ local to your repo(s).
+
+[NOTE]
+In addition to the above alternatives, there are git commands that can take
+exclude patterns directly on the command line. See gitlink:git-ls-files[1]
+for an example of this.
+
[[how-to-merge]]
How to merge
------------
that a branch is created:
-------------------------------------------------
-$ git checkout --track -b origin/maint maint
+$ git checkout --track -b maint origin/maint
-------------------------------------------------
In addition to saving you keystrokes, "git pull" also helps you by
link:cvs-migration.html[git for CVS users] for instructions on how to
set this up.
+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
+exchanging patches and pulling from public repositories--has so many
+advantages over the central shared repository:
+
+ - Git's ability to quickly import and merge patches allows a
+ single maintainer to process incoming changes even at very
+ high rates. And when that becomes too much, git-pull provides
+ an easy way for that maintainer to delegate this job to other
+ maintainers while still allowing optional review of incoming
+ changes.
+ - Since every developer's repository has the same complete copy
+ of the project history, no repository is special, and it is
+ trivial for another developer to take over maintenance of a
+ project, either by mutual agreement, or because a maintainer
+ becomes unresponsive or difficult to work with.
+ - The lack of a central group of "committers" means there is
+ less need for formal decisions about who is "in" and who is
+ "out".
+
[[setting-up-gitweb]]
Allowing web browsing of a repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
independently of the contents or the type of the object: all objects can
be validated by verifying that (a) their hashes match the content of the
file and (b) the object successfully inflates to a stream of bytes that
-forms a sequence of <ascii type without space>
+ <space> + <ascii decimal
-size> + <byte\0> + <binary object data>.
+forms a sequence of <ascii type without space>
{plus} <space> {plus} <ascii decimal
+size> {plus} <byte\0> {plus} <binary object data>.
The structured objects can further have their structure and
connectivity to other objects verified. This is generally done with
include::glossary.txt[]
[[git-quick-start]]
-Appendix A: Git Quick Start
-===========================
+Appendix A: Git Quick Reference
+===============================
-This is a quick summary of the major commands; the following chapters
-will explain how these work in more detail.
+This is a quick summary of the major commands; the previous chapters
+explain how these work in more detail.
[[quick-creating-a-new-repository]]
Creating a new repository
allow people to get to important topics without necessarily reading
everything in between.
-Say something about .gitignore.
-
Scan Documentation/ for other stuff left out; in particular:
howto's
some of technical/?
More details on gitweb?
Write a chapter on using plumbing and writing scripts.
+
+Alternates, clone -reference, etc.
+
+git unpack-objects -r for recovery