diff --git a/Documentation/Makefile b/Documentation/Makefile index f4cbf7e15..c1af22ce0 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -79,7 +79,7 @@ clean: asciidoc -b xhtml11 -d manpage -f asciidoc.conf $< %.1 %.7 : %.xml - xmlto man $< + xmlto -m callouts.xsl man $< %.xml : %.txt asciidoc -b docbook -d manpage -f asciidoc.conf $< diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 318b04fde..8601949e8 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -266,8 +266,8 @@ This recipe appears to work with the current [*1*] Thunderbird from Suse. The following Thunderbird extensions are needed: AboutConfig 0.5 http://aboutconfig.mozdev.org/ - External Editor 0.5.4 - http://extensionroom.mozdev.org/more-info/exteditor + External Editor 0.7.2 + http://globs.org/articles.php?lng=en&pg=8 1) Prepare the patch as a text file using your method of choice. diff --git a/Documentation/callouts.xsl b/Documentation/callouts.xsl new file mode 100644 index 000000000..ad03755d8 --- /dev/null +++ b/Documentation/callouts.xsl @@ -0,0 +1,16 @@ + + + + + + + .sp + + + + + + + .br + + diff --git a/Documentation/config.txt b/Documentation/config.txt index b27b0d5c0..d1a4bec0d 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -64,9 +64,11 @@ core.ignoreStat:: slow, such as Microsoft Windows. See gitlink:git-update-index[1]. False by default. -core.onlyUseSymrefs:: - Always use the "symref" format instead of symbolic links for HEAD - and other symbolic reference files. True by default. +core.preferSymlinkRefs:: + Instead of the default "symref" format for HEAD + and other symbolic reference files, use symbolic links. + This is sometimes needed to work with old scripts that + expect HEAD to be a symbolic link. core.repositoryFormatVersion:: Internal variable identifying the repository format and layout diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 4211c8197..d1360ecde 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -971,7 +971,7 @@ $ git show-branch --topo-order master mybranch The first two lines indicate that it is showing the two branches and the first line of the commit log message from their top-of-the-tree commits, you are currently on `master` branch -(notice the asterisk `*` character), and the first column for +(notice the asterisk `\*` character), and the first column for the later output lines is used to show commits contained in the `master` branch, and the second column for the `mybranch` branch. Three commits are shown along with their log messages. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index c183dc9da..f523ec2fb 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -10,6 +10,10 @@ --stat:: Generate a diffstat instead of a patch. +--summary:: + Output a condensed summary of extended header information + such as creations, renames and mode changes. + --patch-with-stat:: Generate patch and prepend its diffstat. diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index 3ab9b916c..4b5637093 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -61,7 +61,8 @@ $ git prune $ git count-objects <2> $ git repack <3> $ git prune <4> - +------------ ++ <1> running without "--full" is usually cheap and assures the repository health reasonably well. <2> check how many loose objects there are and how much @@ -69,17 +70,16 @@ diskspace is wasted by not repacking. <3> without "-a" repacks incrementally. repacking every 4-5MB of loose objects accumulation may be a good rule of thumb. <4> after repack, prune removes the duplicate loose objects. ------------- Repack a small project into single pack.:: + ------------ $ git repack -a -d <1> $ git prune - +------------ ++ <1> pack all the objects reachable from the refs into one pack and remove unneeded other packs ------------- Individual Developer (Standalone)[[Individual Developer (Standalone)]] @@ -129,10 +129,10 @@ $ git-init-db $ git add . <1> $ git commit -m 'import of frotz source tree.' $ git tag v2.43 <2> - +------------ ++ <1> add everything under the current directory. <2> make a lightweight, unannotated tag. ------------- Create a topic branch and develop.:: + @@ -153,7 +153,8 @@ $ git checkout master <9> $ git pull . alsa-audio <10> $ git log --since='3 days ago' <11> $ git log v2.43.. curses/ <12> - +------------ ++ <1> create a new topic branch. <2> revert your botched changes in "curses/ux_audio_oss.c". <3> you need to tell git if you added a new file; removal and @@ -170,7 +171,6 @@ you originally wrote. combined and include --max-count=10 (show 10 commits), --until='2005-12-10'. <12> view only the changes that touch what's in curses/ directory, since v2.43 tag. ------------- Individual Developer (Participant)[[Individual Developer (Participant)]] @@ -208,7 +208,8 @@ $ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> $ git reset --hard ORIG_HEAD <6> $ git prune <7> $ git fetch --tags <8> - +------------ ++ <1> repeat as needed. <2> extract patches from your branch for e-mail submission. <3> "pull" fetches from "origin" by default and merges into the @@ -221,7 +222,6 @@ area we are interested in. <7> garbage collect leftover objects from reverted pull. <8> from time to time, obtain official tags from the "origin" and store them under .git/refs/tags/. ------------- Push into another repository.:: @@ -239,7 +239,8 @@ satellite$ git push origin <4> mothership$ cd frotz mothership$ git checkout master mothership$ git pull . satellite <5> - +------------ ++ <1> mothership machine has a frotz repository under your home directory; clone from it to start a repository on the satellite machine. @@ -252,7 +253,6 @@ to local "origin" branch. mothership machine. You could use this as a back-up method. <5> on mothership machine, merge the work done on the satellite machine into the master branch. ------------- Branch off of a specific tag.:: + @@ -262,12 +262,12 @@ $ edit/compile/test; git commit -a $ git checkout master $ git format-patch -k -m --stdout v2.6.14..private2.6.14 | git am -3 -k <2> - +------------ ++ <1> create a private branch based on a well known (but somewhat behind) tag. <2> forward port all changes in private2.6.14 branch to master branch without a formal "merging". ------------- Integrator[[Integrator]] @@ -317,7 +317,8 @@ $ git tag -s -m 'GIT 0.99.9x' v0.99.9x <10> $ git fetch ko && git show-branch master maint 'tags/ko-*' <11> $ git push ko <12> $ git push ko v0.99.9x <13> - +------------ ++ <1> see what I was in the middle of doing, if any. <2> see what topic branches I have and think about how ready they are. @@ -346,7 +347,6 @@ In the output from "git show-branch", "master" should have everything "ko-master" has. <12> push out the bleeding edge. <13> push the tag out, too. ------------- Repository Administration[[Repository Administration]] @@ -367,7 +367,6 @@ example of managing a shared central repository. Examples ~~~~~~~~ - Run git-daemon to serve /pub/scm from inetd.:: + ------------ @@ -388,13 +387,13 @@ cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell david:x:1003:1003::/home/david:/usr/bin/git-shell $ grep git /etc/shells <2> /usr/bin/git-shell - +------------ ++ <1> log-in shell is set to /usr/bin/git-shell, which does not allow anything but "git push" and "git pull". The users should get an ssh access to the machine. <2> in many distributions /etc/shells needs to list what is used as the login shell. ------------- CVS-style shared repository.:: + @@ -419,7 +418,8 @@ $ cat info/allowed-users <4> refs/heads/master alice\|cindy refs/heads/doc-update bob refs/tags/v[0-9]* david - +------------ ++ <1> place the developers into the same git group. <2> and make the shared repository writable by the group. <3> use update-hook example by Carl from Documentation/howto/ @@ -427,7 +427,6 @@ for branch policy control. <4> alice and cindy can push into master, only bob can push into doc-update. david is the release manager and is the only person who can create and push version tags. ------------- HTTP server to support dumb protocol transfer.:: + @@ -435,7 +434,7 @@ HTTP server to support dumb protocol transfer.:: dev$ git update-server-info <1> dev$ ftp user@isp.example.com <2> ftp> cp -r .git /home/user/myproject.git - +------------ ++ <1> make sure your info/refs and objects/info/packs are up-to-date <2> upload to public HTTP server hosted by your ISP. ------------- diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index ae24547c8..5e3112943 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -26,7 +26,7 @@ OPTIONS -v:: Be verbose. ---:: +\--:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken for command-line options). diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 71ecd858a..72fb2f89b 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -3,22 +3,27 @@ git-branch(1) NAME ---- -git-branch - Create a new branch, or remove an old one +git-branch - List, create, or delete branches. SYNOPSIS -------- [verse] -'git-branch' [[-f] []] -'git-branch' (-d | -D) +'git-branch' [-r] +'git-branch' [-f] [] +'git-branch' (-d | -D) ... DESCRIPTION ----------- -If no argument is provided, show available branches and mark current -branch with star. Otherwise, create a new branch of name . -If a starting point is also specified, that will be where the branch is -created, otherwise it will be created at the current HEAD. +With no arguments given (or just `-r`) a list of available branches +will be shown, the current branch will be highlighted with an asterisk. -With a `-d` or `-D` option, `` will be deleted. +In its second form, a new branch named will be created. +It will start out with a head equal to the one given as . +If no is given, the branch will be created with a head +equal to that of the currently checked out branch. + +With a `-d` or `-D` option, `` will be deleted. You may +specify more than one branch for deletion. OPTIONS @@ -30,40 +35,56 @@ OPTIONS Delete a branch irrespective of its index status. -f:: - Force a reset of to (or current head). + Force the creation of a new branch even if it means deleting + a branch that already exists with the same name. + +-r:: + List only the "remote" branches. :: The name of the branch to create or delete. :: - Where to create the branch; defaults to HEAD. This - option has no meaning with -d and -D. + The new branch will be created with a HEAD equal to this. It may + be given as a branch name, a commit-id, or a tag. If this option + is omitted, the current branch is assumed. + Examples -~~~~~~~~ +-------- Start development off of a known tag:: + ------------ $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 $ cd my2.6 -$ git branch my2.6.14 v2.6.14 <1> +$ git branch my2.6.14 v2.6.14 <1> $ git checkout my2.6.14 - -<1> These two steps are the same as "checkout -b my2.6.14 v2.6.14". ------------ ++ +<1> This step and the next one could be combined into a single step with +"checkout -b my2.6.14 v2.6.14". Delete unneeded branch:: + ------------ $ git clone git://git.kernel.org/.../git.git my.git $ cd my.git -$ git branch -D todo <1> - +$ git branch -D todo <1> +------------ ++ <1> delete todo branch even if the "master" branch does not have all commits from todo branch. ------------- + + +Notes +----- + +If you are creating a branch that you want to immediately checkout, it's +easier to use the git checkout command with its `-b` option to create +a branch and check it out with a single command. + Author ------ diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 09bd6a553..765c173e1 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -63,7 +63,7 @@ OPTIONS Only meaningful with `--stdin`; paths are separated with NUL character instead of LF. ---:: +\--:: Do not interpret any more arguments as options. The order of the flags used to matter, but not anymore. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 985bb2f82..095128906 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -66,19 +66,19 @@ the `Makefile` to two revisions back, deletes hello.c by mistake, and gets it back from the index. + ------------ -$ git checkout master <1> -$ git checkout master~2 Makefile <2> +$ git checkout master <1> +$ git checkout master~2 Makefile <2> $ rm -f hello.c -$ git checkout hello.c <3> - +$ git checkout hello.c <3> +------------ ++ <1> switch branch <2> take out a file out of other commit -<3> or "git checkout -- hello.c", as in the next example. ------------- +<3> restore hello.c from HEAD of current branch + -If you have an unfortunate branch that is named `hello.c`, the -last step above would be confused as an instruction to switch to -that branch. You should instead write: +If you have an unfortunate branch that is named `hello.c`, this +step would be confused as an instruction to switch to that branch. +You should instead write: + ------------ $ git checkout -- hello.c diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 9a5e37186..893baaa6f 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -11,11 +11,20 @@ SYNOPSIS DESCRIPTION ----------- -Each commit between the fork-point and is examined, and compared against -the change each commit between the fork-point and introduces. -Commits already included in upstream are prefixed with '-' (meaning "drop from -my local pull"), while commits missing from upstream are prefixed with '+' -(meaning "add to the updated upstream"). +The changeset (or "diff") of each commit between the fork-point and +is compared against each commit between the fork-point and . + +Every commit with a changeset that doesn't exist in the other branch +has its id (sha1) reported, prefixed by a symbol. Those existing only +in the branch are prefixed with a minus (-) sign, and those +that only exist in the branch are prefixed with a plus (+) symbol. + +Because git-cherry compares the changeset rather than the commit id +(sha1), you can use git-cherry to find out if a commit you made locally +has been applied under a different commit id. For example, +this will happen if you're feeding patches via email rather +than pushing or pulling commits directly. + OPTIONS ------- diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 36890c543..c61afbcdb 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree SYNOPSIS -------- [verse] -'git-clean' [-d] [-n] [-q] [-x | -X] +'git-clean' [-d] [-n] [-q] [-x | -X] [--] ... DESCRIPTION ----------- @@ -16,6 +16,9 @@ Removes files unknown to git. This allows to clean the working tree from files that are not under version control. If the '-x' option is specified, ignored files are also removed, allowing to remove all build products. +When optional `...` arguments are given, the paths +affected are further limited to those that match them. + OPTIONS ------- diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 131e44574..b333f5104 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -101,7 +101,7 @@ OPTIONS is not allowed. Examples -~~~~~~~~ +-------- Clone from upstream:: + diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 0a7365b9a..38df59ce2 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -106,7 +106,7 @@ but can be used to amend a merge commit. index and the latest commit does not match on the specified paths to avoid confusion. ---:: +\--:: Do not interpret any more arguments as options. ...:: diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 47216f488..198ce77a8 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -7,13 +7,23 @@ git-count-objects - Reports on unpacked objects SYNOPSIS -------- -'git-count-objects' +'git-count-objects' [-v] DESCRIPTION ----------- This counts the number of unpacked object files and disk space consumed by them, to help you decide when it is a good time to repack. + +OPTIONS +------- +-v:: + In addition to the number of loose objects and disk + space consumed, it reports the number of in-pack + objects, and number of objects that can be removed by + running `git-prune-packed`. + + Author ------ Written by Junio C Hamano diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index d30435a9e..56bd3e517 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -8,7 +8,7 @@ git-cvsexportcommit - Export a commit to a CVS checkout SYNOPSIS -------- -'git-cvsexportcommmit' [-h] [-v] [-c] [-p] [PARENTCOMMIT] COMMITID +'git-cvsexportcommmit' [-h] [-v] [-c] [-p] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID DESCRIPTION @@ -39,6 +39,13 @@ OPTIONS Be pedantic (paranoid) when applying patches. Invokes patch with --fuzz=0 +-f:: + Force the merge even if the files are not up to date. + +-m:: + Prepend the commit message with the provided prefix. + Useful for patch series and the like. + -v:: Verbose. diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 216916985..906830d4b 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -92,7 +92,7 @@ separated with a single space are given. Furthermore, it lists only files which were modified from all parents. --cc:: +--cc:: This flag changes the way a merge commit patch is displayed, in a similar way to the '-c' option. It implies the '-c' and '-p' options and further compresses the patch output diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 890931c89..7267bcd7a 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -46,40 +46,41 @@ EXAMPLES Various ways to check your working tree:: + ------------ -$ git diff <1> -$ git diff --cached <2> -$ git diff HEAD <3> - +$ git diff <1> +$ git diff --cached <2> +$ git diff HEAD <3> +------------ ++ <1> changes in the working tree since your last git-update-index. <2> changes between the index and your last commit; what you would be committing if you run "git commit" without "-a" option. <3> changes in the working tree since your last commit; what you would be committing if you run "git commit -a" ------------- Comparing with arbitrary commits:: + ------------ -$ git diff test <1> -$ git diff HEAD -- ./test <2> -$ git diff HEAD^ HEAD <3> - +$ git diff test <1> +$ git diff HEAD -- ./test <2> +$ git diff HEAD^ HEAD <3> +------------ ++ <1> instead of using the tip of the current branch, compare with the tip of "test" branch. <2> instead of comparing with the tip of "test" branch, compare with the tip of the current branch, but limit the comparison to the file "test". <3> compare the version before the last commit and the last commit. ------------- Limiting the diff output:: + ------------ -$ git diff --diff-filter=MRC <1> -$ git diff --name-status -r <2> -$ git diff arch/i386 include/asm-i386 <3> - +$ git diff --diff-filter=MRC <1> +$ git diff --name-status -r <2> +$ git diff arch/i386 include/asm-i386 <3> +------------ ++ <1> show only modification, rename and copy, but not addition nor deletion. <2> show only names and the nature of change, but not actual @@ -88,18 +89,17 @@ which in turn also disables recursive behaviour, so without -r you would only see the directory name if there is a change in a file in a subdirectory. <3> limit diff output to named subtrees. ------------- Munging the diff output:: + ------------ -$ git diff --find-copies-harder -B -C <1> -$ git diff -R <2> - +$ git diff --find-copies-harder -B -C <1> +$ git diff -R <2> +------------ ++ <1> spend extra cycles to find renames, copies and complete rewrites (very expensive). <2> output diff in reverse. ------------- Author diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index d55456ae9..74102b794 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -8,43 +8,82 @@ git-grep - Print lines matching a pattern SYNOPSIS -------- -'git-grep' [