aboutsummaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJunio C Hamano <junkio@cox.net>2007-05-20 00:19:30 -0700
committerJunio C Hamano <junkio@cox.net>2007-05-20 00:19:30 -0700
commit03f6db0ec058ca1d34672a3100293c3bf56c3b6b (patch)
tree38949f1dc69f9423ea74e99381ce6083d740540a /Documentation
parent404fdef22f1084141aeef5781d5a322554fed481 (diff)
parentf7b47b273ed2c9e9b298c4f5dd02884b46dfbced (diff)
downloadgit-03f6db0ec058ca1d34672a3100293c3bf56c3b6b.tar.gz
git-03f6db0ec058ca1d34672a3100293c3bf56c3b6b.tar.xz
Merge branch 'maint' to synchronize with 1.5.1.6
* maint: GIT 1.5.1.6 git-svn: don't minimize-url when doing an init that tracks multiple paths git-svn: avoid crashing svnserve when creating new directories user-manual: Add section on ignoring files user-manual: finding commits referencing given file content user-manual: discourage shared repository tutorial: revise index introduction tutorials: add user-manual links Conflicts: GIT-VERSION-GEN RelNotes
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/RelNotes-1.5.1.5.txt8
-rw-r--r--Documentation/RelNotes-1.5.1.6.txt45
-rw-r--r--Documentation/tutorial-2.txt3
-rw-r--r--Documentation/tutorial.txt100
-rw-r--r--Documentation/user-manual.txt108
5 files changed, 205 insertions, 59 deletions
diff --git a/Documentation/RelNotes-1.5.1.5.txt b/Documentation/RelNotes-1.5.1.5.txt
index 85e821c43..b0ab8eb37 100644
--- a/Documentation/RelNotes-1.5.1.5.txt
+++ b/Documentation/RelNotes-1.5.1.5.txt
@@ -1,4 +1,4 @@
-GIT v1.5.1.5 Release Notes (draft)
+GIT v1.5.1.5 Release Notes
==========================
Fixes since v1.5.1.4
@@ -40,9 +40,3 @@ Fixes since v1.5.1.4
compilers on Sun.
- Many many documentation fixes and updates.
-
---
-exec >/var/tmp/1
-O=v1.5.1.4-48-gcecb98a
-echo O=`git describe refs/heads/maint`
-git shortlog --no-merges $O..refs/heads/maint
diff --git a/Documentation/RelNotes-1.5.1.6.txt b/Documentation/RelNotes-1.5.1.6.txt
new file mode 100644
index 000000000..55f3ac13e
--- /dev/null
+++ b/Documentation/RelNotes-1.5.1.6.txt
@@ -0,0 +1,45 @@
+GIT v1.5.1.6 Release Notes
+==========================
+
+Fixes since v1.5.1.4
+--------------------
+
+* Bugfixes
+
+ - git-send-email did not understand aliases file for mutt, which
+ allows leading whitespaces.
+
+ - git-format-patch emitted Content-Type and Content-Transfer-Encoding
+ headers for non ASCII contents, but failed to add MIME-Version.
+
+ - git-name-rev had a buffer overrun with a deep history.
+
+ - contributed script import-tars did not get the directory in
+ tar archives interpreted correctly.
+
+ - git-svn was reported to segfault for many people on list and
+ #git; hopefully this has been fixed.
+
+ - git-svn also had a bug to crash svnserve by sending a bad
+ sequence of requests.
+
+ - "git-svn clone" does not try to minimize the URL
+ (i.e. connect to higher level hierarchy) by default, as this
+ can prevent clone to fail if only part of the repository
+ (e.g. 'trunk') is open to public.
+
+ - "git checkout branch^0" did not detach the head when you are
+ already on 'branch'; backported the fix from the 'master'.
+
+ - "git-config section.var" did not correctly work when
+ existing configuration file had both [section] and [section "name"]
+ next to each other.
+
+ - "git clone ../other-directory" was fooled if the current
+ directory $PWD points at is a symbolic link.
+
+ - (build) tree_entry_extract() function was both static inline
+ and extern, which caused trouble compiling with Forte12
+ compilers on Sun.
+
+ - Many many documentation fixes and updates.
diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt
index af8d43bd1..5c39a165f 100644
--- a/Documentation/tutorial-2.txt
+++ b/Documentation/tutorial-2.txt
@@ -391,6 +391,9 @@ with the commands mentioned in link:everyday.html[Everyday git]. You
should be able to find any unknown jargon in the
link:glossary.html[Glossary].
+The link:user-manual.html[Git User's Manual] provides a more
+comprehensive introduction to git.
+
The link:cvs-migration.html[CVS migration] document explains how to
import a CVS repository into git, and shows how to use git in a
CVS-like way.
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 99efce457..f55d4083e 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -4,6 +4,10 @@ A tutorial introduction to git (for version 1.5.1 or newer)
This tutorial explains how to import a new project into git, make
changes to it, and share changes with other developers.
+If you are instead primarily interested in using git to fetch a project,
+for example, to test the latest version, you may prefer to start with
+the first two chapters of link:user-manual.html[The Git User's Manual].
+
First, note that you can get documentation for a command such as "git
diff" with:
@@ -40,42 +44,67 @@ Initialized empty Git repository in .git/
------------------------------------------------
You've now initialized the working directory--you may notice a new
-directory created, named ".git". Tell git that you want it to track
-every file under the current directory (note the '.') with:
+directory created, named ".git".
+
+Next, tell git to take a snapshot of the contents of all files under the
+current directory (note the '.'), with gitlink:git-add[1]:
------------------------------------------------
$ git add .
------------------------------------------------
-Finally,
+This snapshot is now stored in a temporary staging area which git calls
+the "index". You can permanently store the contents of the index in the
+repository with gitlink:git-commit[1]:
------------------------------------------------
$ git commit
------------------------------------------------
-will prompt you for a commit message, then record the current state
-of all the files to the repository.
+This will prompt you for a commit message. You've now stored the first
+version of your project in git.
Making changes
--------------
-Try modifying some files, then run
+Modify some files, then add their updated contents to the index:
------------------------------------------------
-$ git diff
+$ git add file1 file2 file3
------------------------------------------------
-to review your changes. When you're done, tell git that you
-want the updated contents of these files in the commit and then
-make a commit, like this:
+You are now ready to commit. You can see what is about to be committed
+using gitlink:git-diff[1] with the --cached option:
+
+------------------------------------------------
+$ git diff --cached
+------------------------------------------------
+
+(Without --cached, gitlink:git-diff[1] will show you any changes that
+you've made but not yet added to the index.) You can also get a brief
+summary of the situation with gitlink:git-status[1]:
+
+------------------------------------------------
+$ git status
+# On branch master
+# Changes to be committed:
+# (use "git reset HEAD <file>..." to unstage)
+#
+# modified: file1
+# modified: file2
+# modified: file3
+#
+------------------------------------------------
+
+If you need to make any further adjustments, do so now, and then add any
+newly modified content to the index. Finally, commit your changes with:
------------------------------------------------
-$ git add file1 file2 file3
$ git commit
------------------------------------------------
This will again prompt your for a message describing the change, and then
-record the new versions of the files you listed.
+record a new version of the project.
Alternatively, instead of running `git add` beforehand, you can use
@@ -83,7 +112,8 @@ Alternatively, instead of running `git add` beforehand, you can use
$ git commit -a
------------------------------------------------
-which will automatically notice modified (but not new) files.
+which will automatically notice any modified (but not new) files, add
+them to the index, and commit, all in one step.
A note on commit messages: Though not required, it's a good idea to
begin the commit message with a single short (less than 50 character)
@@ -92,45 +122,15 @@ thorough description. Tools that turn commits into email, for
example, use the first line on the Subject: line and the rest of the
commit in the body.
-
Git tracks content not files
----------------------------
-With git you have to explicitly "add" all the changed _content_ you
-want to commit together. This can be done in a few different ways:
-
-1) By using 'git add <file_spec>...'
-
-This can be performed multiple times before a commit. Note that this
-is not only for adding new files. Even modified files must be
-added to the set of changes about to be committed. The "git status"
-command gives you a summary of what is included so far for the
-next commit. When done you should use the 'git commit' command to
-make it real.
-
-Note: don't forget to 'add' a file again if you modified it after the
-first 'add' and before 'commit'. Otherwise only the previous added
-state of that file will be committed. This is because git tracks
-content, so what you're really 'adding' to the commit is the *content*
-of the file in the state it is in when you 'add' it.
-
-2) By using 'git commit -a' directly
-
-This is a quick way to automatically 'add' the content from all files
-that were modified since the previous commit, and perform the actual
-commit without having to separately 'add' them beforehand. This will
-not add content from new files i.e. files that were never added before.
-Those files still have to be added explicitly before performing a
-commit.
-
-But here's a twist. If you do 'git commit <file1> <file2> ...' then only
-the changes belonging to those explicitly specified files will be
-committed, entirely bypassing the current "added" changes. Those "added"
-changes will still remain available for a subsequent commit though.
-
-However, for normal usage you only have to remember 'git add' + 'git commit'
-and/or 'git commit -a'.
-
+Many revision control systems provide an "add" command that tells the
+system to start tracking changes to a new file. Git's "add" command
+does something simpler and more powerful: `git add` is used both for new
+and newly modified files, and in both cases it takes a snapshot of the
+given files and stages that content in the index, ready for inclusion in
+the next commit.
Viewing the changelog
---------------------
@@ -564,7 +564,7 @@ link:tutorial-2.html[Part two of this tutorial] explains the object
database, the index file, and a few other odds and ends that you'll
need to make the most of git.
-If you don't want to consider with that right away, a few other
+If you don't want to continue with that right away, a few other
digressions that may be interesting at this point are:
* gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index c4bff474d..52247aa71 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -921,6 +921,22 @@ echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"
and then he just cut-and-pastes the output commands after verifying that
they look OK.
+Finding commits referencing a file with given 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
===================
@@ -1073,6 +1089,75 @@ description. Tools that turn commits into email, for example, use
the first line on the Subject line and the rest of the commit in the
body.
+[[ignoring-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
+"Exclude Patterns" section of the gitlink:git-ls-files[1] 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
------------
@@ -1857,6 +1942,27 @@ all push to and pull from a single shared repository. See
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3816,8 +3922,6 @@ Think about how to create a clear chapter dependency graph that will
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/?