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.
Date: Sat Dec 2 22:22:25 2006 -0800
[XFRM]: Fix aevent structuring to be more complete.
-
+
aevents can not uniquely identify an SA. We break the ABI with this
patch, but consensus is that since it is not yet utilized by any
(known) application then it is fine (better do it now than later).
-
+
Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
Signed-off-by: David S. Miller <davem@davemloft.net>
--- a/Documentation/networking/xfrm_sync.txt
+++ b/Documentation/networking/xfrm_sync.txt
@@ -47,10 +47,13 @@ aevent_id structure looks like:
-
+
struct xfrm_aevent_id {
struct xfrm_usersa_id sa_id;
+ xfrm_address_t saddr;
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
===================
-------------------------------------------------
As a special shortcut,
-
+
-------------------------------------------------
$ git commit -a
-------------------------------------------------
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
------------
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,
+old history using, for example,
-------------------------------------------------
$ git log master@{1}
reference pointing to it, for example, a new branch:
------------------------------------------------
-$ git branch recovered-branch 7281251ddd
+$ git branch recovered-branch 7281251ddd
------------------------------------------------
Other types of dangling objects (blobs and trees) are also possible, and
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
you push
your personal repo ------------------> your public repo
- ^ |
+ ^ |
| |
| you pull | they pull
| |
(For an explanation of the last two lines, see
gitlink:git-update-server-info[1], and the documentation
-link:hooks.txt[Hooks used by git].)
+link:hooks.html[Hooks used by git].)
Advertise the url of proj.git. Anybody else should then be able to
clone or pull from that url, for example with a commandline like:
Another way to collaborate is by using a model similar to that
commonly used in CVS, where several developers with special rights
all push to and pull from a single shared repository. See
-link:cvs-migration.txt[git for CVS users] for instructions on how to
+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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\ \
a--b--c--m <-- mywork
................................................
-
+
However, if you prefer to keep the history in mywork a simple series of
commits without any merges, you may instead choose to use
gitlink:git-rebase[1]:
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
just going to confuse people. So aim for the notion of "one root object
-per project", even if git itself does not enforce that.
+per project", even if git itself does not enforce that.
A <<def_tag_object,"tag" object>> symbolically identifies and can be
used to sign other objects. It contains the identifier and type of
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
known tree object, or update/compare it with a live tree that is being
developed. If you blow the directory cache away entirely, you generally
haven't lost any information as long as you have the name of the tree
-that it described.
+that it described.
At the same time, the index is at the same time also the
staging area for creating new trees, and creating a new tree always
work *purely* on the index file (showing the current state of the
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:
+main combinations:
[[working-directory-to-index]]
working directory -> index
leaving _some_ of the new objects in the object database, but just
dangling and useless.
-Anyway, once you are sure that you're not interested in any dangling
+Anyway, once you are sure that you're not interested in any dangling
state, you can just prune all unreachable objects:
------------------------------------------------
repository - it's kind of like doing a filesystem fsck recovery: you
don't want to do that while the filesystem is mounted.
-(The same is true of "git-fsck" itself, btw - but since
-git-fsck never actually *changes* the repository, it just reports
-on what it found, git-fsck itself is never "dangerous" to run.
-Running it while somebody is actually changing the repository can cause
-confusing and scary messages, but it won't actually do anything bad. In
-contrast, running "git prune" while somebody is actively changing the
+(The same is true of "git-fsck" itself, btw - but since
+git-fsck never actually *changes* the repository, it just reports
+on what it found, git-fsck itself is never "dangerous" to run.
+Running it while somebody is actually changing the repository can cause
+confusing and scary messages, but it won't actually do anything bad. In
+contrast, running "git prune" while somebody is actively changing the
repository is a *BAD* idea).
[[birdview-on-the-source-code]]
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