Merge branch 'maint' of git://linux-nfs.org/~bfields/git into maint
* 'maint' of git://linux-nfs.org/~bfields/git: 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
This commit is contained in:
commit
2be2e267aa
@ -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
|
should be able to find any unknown jargon in the
|
||||||
link:glossary.html[Glossary].
|
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
|
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
|
import a CVS repository into git, and shows how to use git in a
|
||||||
CVS-like way.
|
CVS-like way.
|
||||||
|
@ -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
|
This tutorial explains how to import a new project into git, make
|
||||||
changes to it, and share changes with other developers.
|
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
|
First, note that you can get documentation for a command such as "git
|
||||||
diff" with:
|
diff" with:
|
||||||
|
|
||||||
@ -40,42 +44,67 @@ Initialized empty Git repository in .git/
|
|||||||
------------------------------------------------
|
------------------------------------------------
|
||||||
|
|
||||||
You've now initialized the working directory--you may notice a new
|
You've now initialized the working directory--you may notice a new
|
||||||
directory created, named ".git". Tell git that you want it to track
|
directory created, named ".git".
|
||||||
every file under the current directory (note the '.') with:
|
|
||||||
|
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 .
|
$ 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
|
$ git commit
|
||||||
------------------------------------------------
|
------------------------------------------------
|
||||||
|
|
||||||
will prompt you for a commit message, then record the current state
|
This will prompt you for a commit message. You've now stored the first
|
||||||
of all the files to the repository.
|
version of your project in git.
|
||||||
|
|
||||||
Making changes
|
Making changes
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
Try modifying some files, then run
|
Modify some files, then add their updated contents to the index:
|
||||||
|
|
||||||
------------------------------------------------
|
|
||||||
$ git diff
|
|
||||||
------------------------------------------------
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
------------------------------------------------
|
------------------------------------------------
|
||||||
$ git add file1 file2 file3
|
$ git add file1 file2 file3
|
||||||
|
------------------------------------------------
|
||||||
|
|
||||||
|
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 commit
|
$ git commit
|
||||||
------------------------------------------------
|
------------------------------------------------
|
||||||
|
|
||||||
This will again prompt your for a message describing the change, and then
|
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
|
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
|
$ 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
|
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)
|
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
|
example, use the first line on the Subject: line and the rest of the
|
||||||
commit in the body.
|
commit in the body.
|
||||||
|
|
||||||
|
|
||||||
Git tracks content not files
|
Git tracks content not files
|
||||||
----------------------------
|
----------------------------
|
||||||
|
|
||||||
With git you have to explicitly "add" all the changed _content_ you
|
Many revision control systems provide an "add" command that tells the
|
||||||
want to commit together. This can be done in a few different ways:
|
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
|
||||||
1) By using 'git add <file_spec>...'
|
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
|
||||||
This can be performed multiple times before a commit. Note that this
|
the next commit.
|
||||||
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'.
|
|
||||||
|
|
||||||
|
|
||||||
Viewing the changelog
|
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
|
database, the index file, and a few other odds and ends that you'll
|
||||||
need to make the most of git.
|
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:
|
digressions that may be interesting at this point are:
|
||||||
|
|
||||||
* gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
|
* gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
|
||||||
|
@ -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
|
and then he just cut-and-pastes the output commands after verifying that
|
||||||
they look OK.
|
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]]
|
||||||
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
|
the first line on the Subject line and the rest of the commit in the
|
||||||
body.
|
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]]
|
||||||
How to merge
|
How to merge
|
||||||
------------
|
------------
|
||||||
@ -1857,6 +1942,27 @@ 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.txt[git for CVS users] for instructions on how to
|
||||||
set this up.
|
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]]
|
[[setting-up-gitweb]]
|
||||||
Allowing web browsing of a repository
|
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
|
allow people to get to important topics without necessarily reading
|
||||||
everything in between.
|
everything in between.
|
||||||
|
|
||||||
Say something about .gitignore.
|
|
||||||
|
|
||||||
Scan Documentation/ for other stuff left out; in particular:
|
Scan Documentation/ for other stuff left out; in particular:
|
||||||
howto's
|
howto's
|
||||||
some of technical/?
|
some of technical/?
|
||||||
|
Loading…
Reference in New Issue
Block a user