diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt index af8d43bd12..5c39a165f5 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 99efce4576..f55d4083ed 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 ..." 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 ...' - -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 ...' 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 f4843f4e90..534ece464b 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.txt[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/?