diff options
Diffstat (limited to 'Documentation')
31 files changed, 538 insertions, 165 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 43781fb248..4144d1e086 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -2,8 +2,8 @@ MAN1_TXT= \ $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) \ gitk.txt -MAN5_TXT=gitattributes.txt gitignore.txt gitcli.txt gitmodules.txt -MAN7_TXT=git.txt +MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt +MAN7_TXT=git.txt gitcli.txt MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) @@ -18,7 +18,6 @@ ARTICLES += cvs-migration ARTICLES += diffcore ARTICLES += howto-index ARTICLES += repository-layout -ARTICLES += hooks ARTICLES += everyday ARTICLES += git-tools ARTICLES += glossary diff --git a/Documentation/config.txt b/Documentation/config.txt index 824e416e9f..217980f48d 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -399,6 +399,21 @@ branch.autosetupmerge:: done when the starting point is either a local branch or remote branch. This option defaults to true. +branch.autosetuprebase:: + When a new branch is created with `git-branch` or `git-checkout` + that tracks another branch, this variable tells git to set + up pull to rebase instead of merge (see "branch.<name>.rebase"). + When `never`, rebase is never automatically set to true. + When `local`, rebase is set to true for tracked branches of + other local branches. + When `remote`, rebase is set to true for tracked branches of + remote branches. + When `always`, rebase will be set to true for all tracking + branches. + See "branch.autosetupmerge" for details on how to set up a + branch to track another branch. + This option defaults to never. + branch.<name>.remote:: When in branch <name>, it tells `git fetch` which remote to fetch. If this option is not given, `git fetch` defaults to remote "origin". @@ -426,7 +441,8 @@ branch.<name>.mergeoptions:: branch.<name>.rebase:: When true, rebase the branch <name> on top of the fetched branch, - instead of merging the default branch from the default remote. + instead of merging the default branch from the default remote when + "git pull" is run. *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] for details). @@ -684,6 +700,36 @@ specified as 'gitcvs.<access_method>.<varname>' (where 'access_method' is one of "ext" and "pserver") to make them apply only for the given access method. +gui.commitmsgwidth:: + Defines how wide the commit message window is in the + linkgit:git-gui[1]. "75" is the default. + +gui.diffcontext:: + Specifies how many context lines should be used in calls to diff + made by the linkgit:git-gui[1]. The default is "5". + +gui.matchtrackingbranch:: + Determines if new branches created with linkgit:git-gui[1] should + default to tracking remote branches with matching names or + not. Default: "false". + +gui.newbranchtemplate:: + Is used as suggested name when creating new branches using the + linkgit:git-gui[1]. + +gui.pruneduringfetch:: + "true" if linkgit:git-gui[1] should prune tracking branches when + performing a fetch. The default value is "false". + +gui.trustmtime:: + Determines if linkgit:git-gui[1] should trust the file modification + timestamp or not. By default the timestamps are not trusted. + +gui.spellingdictionary:: + Specifies the dictionary used for spell checking commit messages in + the linkgit:git-gui[1]. When set to "none" spell checking is turned + off. + help.browser:: Specify the browser that will be used to display help in the 'web' format. See linkgit:git-help[1]. @@ -779,37 +825,16 @@ man.viewer:: Specify the programs that may be used to display help in the 'man' format. See linkgit:git-help[1]. -merge.summary:: - Whether to include summaries of merged commits in newly created - merge commit messages. False by default. - -merge.tool:: - Controls which merge resolution program is used by - linkgit:git-mergetool[1]. Valid built-in values are: "kdiff3", - "tkdiff", "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", and - "opendiff". Any other value is treated is custom merge tool - and there must be a corresponing mergetool.<tool>.cmd option. - -merge.verbosity:: - Controls the amount of output shown by the recursive merge - strategy. Level 0 outputs nothing except a final error - message if conflicts were detected. Level 1 outputs only - conflicts, 2 outputs conflicts and file changes. Level 5 and - above outputs debugging information. The default is level 2. - Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable. - -merge.<driver>.name:: - Defines a human readable name for a custom low-level - merge driver. See linkgit:gitattributes[5] for details. - -merge.<driver>.driver:: - Defines the command that implements a custom low-level - merge driver. See linkgit:gitattributes[5] for details. - -merge.<driver>.recursive:: - Names a low-level merge driver to be used when - performing an internal merge between common ancestors. - See linkgit:gitattributes[5] for details. +include::merge-config.txt[] + +man.<tool>.cmd:: + Specify the command to invoke the specified man viewer. The + specified command is evaluated in shell with the man page + passed as argument. (See linkgit:git-help[1].) + +man.<tool>.path:: + Override the path for the given tool that may be used to + display help in the 'man' format. See linkgit:git-help[1]. mergetool.<tool>.path:: Override the path for the given tool. This is useful in case @@ -921,6 +946,10 @@ remote.<name>.push:: The default set of "refspec" for linkgit:git-push[1]. See linkgit:git-push[1]. +remote.<name>.mirror:: + If true, pushing to this remote will automatically behave + as if the `\--mirror` option was given on the command line. + remote.<name>.skipDefaultUpdate:: If true, this remote will be skipped by default when updating using the update subcommand of linkgit:git-remote[1]. diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index 00f2e36b2e..374bc87b10 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -137,7 +137,7 @@ Advanced Shared Repository Management Git allows you to specify scripts called "hooks" to be run at certain points. You can use these, for example, to send all commits to the shared -repository to a mailing list. See link:hooks.html[Hooks used by git]. +repository to a mailing list. See linkgit:githooks[5][Hooks used by git]. You can enforce finer grained permissions using update hooks. See link:howto/update-hook-example.txt[Controlling access to branches using diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 35e67a06e4..e0e730b6c4 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -71,7 +71,9 @@ OPTIONS the specified filepatterns before exiting. -u:: - Update only files that git already knows about. This is similar + Update only files that git already knows about, staging modified + content for commit and marking deleted files for removal. This + is similar to what "git commit -a" does in preparation for making a commit, except that the update is limited to paths specified on the command line. If no paths are specified, all tracked files in the @@ -98,21 +100,27 @@ those in info/exclude. See link:repository-layout.html[repository layout]. EXAMPLES -------- -git-add Documentation/\\*.txt:: - Adds content from all `\*.txt` files under `Documentation` - directory and its subdirectories. +* Adds content from all `\*.txt` files under `Documentation` directory +and its subdirectories: ++ +------------ +$ git add Documentation/\\*.txt +------------ + Note that the asterisk `\*` is quoted from the shell in this example; this lets the command to include the files from subdirectories of `Documentation/` directory. -git-add git-*.sh:: - - Considers adding content from all git-*.sh scripts. - Because this example lets shell expand the asterisk - (i.e. you are listing the files explicitly), it does not - consider `subdir/git-foo.sh`. +* Considers adding content from all git-*.sh scripts: ++ +------------ +$ git add git-*.sh +------------ ++ +Because this example lets shell expand the asterisk (i.e. you are +listing the files explicitly), it does not consider +`subdir/git-foo.sh`. Interactive mode ---------------- diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 698ffde7ce..0b8b0ebba7 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -85,7 +85,7 @@ Oh, and then after you want to reset to the original head, do a $ git bisect reset ------------------------------------------------ -to get back to the master branch, instead of being in one of the +to get back to the original branch, instead of being in one of the bisection branches ("git bisect start" will do that for you too, actually: it will reset the bisection state, and before it does that it checks that you're not using some old bisection branch). @@ -224,6 +224,55 @@ tree to the pristine state. Finally the "run" script can exit with the status of the real test to let "git bisect run" command loop to know the outcome. +EXAMPLES +-------- + +* Automatically bisect a broken build between v1.2 and HEAD: ++ +------------ +$ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good +$ git bisect run make # "make" builds the app +------------ + +* Automatically bisect a broken test suite: ++ +------------ +$ cat ~/test.sh +#!/bin/sh +make || exit 125 # this "skip"s broken builds +make test # "make test" runs the test suite +$ git bisect start v1.3 v1.1 -- # v1.3 is bad, v1.1 is good +$ git bisect run ~/test.sh +------------ ++ +Here we use a "test.sh" custom script. In this script, if "make" +fails, we "skip" the current commit. ++ +It's safer to use a custom script outside the repo to prevent +interactions between the bisect, make and test processes and the +script. ++ +And "make test" should "exit 0", if the test suite passes, and +"exit 1" (for example) otherwise. + +* Automatically bisect a broken test case: ++ +------------ +$ cat ~/test.sh +#!/bin/sh +make || exit 125 # this "skip"s broken builds +~/check_test_case.sh # does the test case passes ? +$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 +$ git bisect run ~/test.sh +------------ ++ +Here "check_test_case.sh" should "exit 0", if the test case passes, +and "exit 1" (for example) otherwise. ++ +It's safer if both "test.sh" and "check_test_case.sh" scripts are +outside the repo to prevent interactions between the bisect, make and +test processes and the scripts. + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 6f07a17a2c..c824d88742 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,7 +8,7 @@ git-branch - List, create, or delete branches SYNOPSIS -------- [verse] -'git-branch' [--color | --no-color] [-r | -a] +'git-branch' [--color | --no-color] [-r | -a] [--merged | --no-merged] [-v [--abbrev=<length> | --no-abbrev]] [--contains <commit>] 'git-branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>] @@ -24,6 +24,8 @@ and option `-a` shows both. With `--contains <commit>`, shows only the branches that contains the named commit (in other words, the branches whose tip commits are descendant of the named commit). +With `--merged`, only branches merged into HEAD will be listed, and +with `--no-merged` only branches not merged into HEAD will be listed. In its second form, a new branch named <branchname> will be created. It will start out with a head equal to the one given as <start-point>. @@ -118,6 +120,15 @@ OPTIONS --no-track:: Ignore the branch.autosetupmerge configuration variable. +--contains <commit>:: + Only list branches which contain the specified commit. + +--merged:: + Only list branches which are fully contained by HEAD. + +--no-merged:: + Do not list branches which are fully contained by HEAD. + <branchname>:: The name of the branch to create or delete. The new branch name must pass all checks defined by @@ -175,6 +186,18 @@ 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. +The options `--contains`, `--merged` and `--no-merged` serves three related +but different purposes: + +- `--contains <commit>` is used to find all branches which will need + special attention if <commit> were to be rebased or amended, since those + branches contain the specified <commit>. + +- `--merged` is used to find all branches which can be safely deleted, + since those branches are fully contained by HEAD. + +- `--no-merged` is used to find branches which are candidates for merging + into HEAD, since those branches are not fully contained by HEAD. Author ------ diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index f0beb412e6..ca048f46f6 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -7,7 +7,7 @@ git-cherry-pick - Apply the change introduced by an existing commit SYNOPSIS -------- -'git-cherry-pick' [--edit] [-n] [-m parent-number] [-x] <commit> +'git-cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] <commit> DESCRIPTION ----------- @@ -64,6 +64,9 @@ OPTIONS This is useful when cherry-picking more than one commits' effect to your working tree in a row. +-s|--signoff:: + Add Signed-off-by line at the end of the commit message. + Author ------ diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 4bb51cc06e..c3c9f5b902 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -87,7 +87,7 @@ OPTIONS --no-verify:: This option bypasses the pre-commit and commit-msg hooks. - See also link:hooks.html[hooks]. + See also linkgit:githooks[5][hooks]. --allow-empty:: Usually recording a commit that has the exact same tree as its @@ -292,7 +292,7 @@ order). HOOKS ----- This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, -and `post-commit` hooks. See link:hooks.html[hooks] for more +and `post-commit` hooks. See linkgit:githooks[5][hooks] for more information. diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 9a47b4c397..363c36d694 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -65,11 +65,17 @@ OPTIONS -w:: Specify the location of the CVS checkout to use for the export. This option does not require GIT_DIR to be set before execution if the - current directory is within a git repository. + current directory is within a git repository. The default is the + value of 'cvsexportcommit.cvsdir'. -v:: Verbose. +CONFIGURATION +------------- +cvsexportcommit.cvsdir:: + The default location of the CVS checkout to use for the export. + EXAMPLES -------- diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index d9aa2f2980..69e1ab750d 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -13,9 +13,10 @@ SYNOPSIS DESCRIPTION ----------- The command finds the most recent tag that is reachable from a -commit, and if the commit itself is pointed at by the tag, shows -the tag. Otherwise, it suffixes the tag name with the number of -additional commits and the abbreviated object name of the commit. +commit. If the tag points to the commit, then only the tag is +shown. Otherwise, it suffixes the tag name with the number of +additional commits on top of the tagged object and the +abbreviated object name of the most recent commit. OPTIONS diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 6454e49bf2..506c37af70 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -133,10 +133,16 @@ use "--tag-name-filter cat" to simply update the tags. In this case, be very careful and make sure you have the old tags backed up in case the conversion has run afoul. + -Note that there is currently no support for proper rewriting of -tag objects; in layman terms, if the tag has a message or signature -attached, the rewritten tag won't have it. Sorry. (It is by -definition impossible to preserve signatures at any rate.) +Nearly proper rewriting of tag objects is supported. If the tag has +a message attached, a new tag object will be created with the same message, +author, and timestamp. If the tag has a signature attached, the +signature will be stripped. It is by definition impossible to preserve +signatures. The reason this is "nearly" proper, is because ideally if +the tag did not change (points to the same object, has the same name, etc.) +it should retain any signature. That is not the case, signatures will always +be removed, buyer beware. There is also no support for changing the +author or timestamp (or the tag message for that matter). Tags which point +to other tags will be rewritten to point to the underlying commit. --subdirectory-filter <directory>:: Only look at the history which touches the given subdirectory. @@ -177,6 +183,10 @@ or copyright violation) from all commits: git filter-branch --tree-filter 'rm filename' HEAD ------------------------------------------------------- +However, if the file is absent from the tree of some commit, +a simple `rm filename` will fail for that tree and commit. +Thus you may instead want to use `rm -f filename` as the script. + A significantly faster version: -------------------------------------------------------------------------- diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 8615ae353e..457cf42561 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -9,8 +9,8 @@ git-fmt-merge-msg - Produce a merge commit message SYNOPSIS -------- [verse] -git-fmt-merge-msg [--summary | --no-summary] <$GIT_DIR/FETCH_HEAD -git-fmt-merge-msg [--summary | --no-summary] -F <file> +git-fmt-merge-msg [--log | --no-log] <$GIT_DIR/FETCH_HEAD +git-fmt-merge-msg [--log | --no-log] -F <file> DESCRIPTION ----------- @@ -24,15 +24,19 @@ automatically invoking `git-merge`. OPTIONS ------- ---summary:: +--log:: In addition to branch names, populate the log message with one-line descriptions from the actual commits that are being merged. ---no-summary:: +--no-log:: Do not list one-line descriptions from the actual commits being merged. +--summary,--no-summary:: + Synonyms to --log and --no-log; these are deprecated and will be + removed in the future. + --file <file>, -F <file>:: Take the list of merged objects from <file> instead of stdin. @@ -40,10 +44,14 @@ OPTIONS CONFIGURATION ------------- -merge.summary:: +merge.log:: Whether to include summaries of merged commits in newly merge commit messages. False by default. +merge.summary:: + Synonym to `merge.log`; this is deprecated and will be removed in + the future. + SEE ALSO -------- linkgit:git-merge[1] diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index b5207b7604..c60ce123ec 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -156,6 +156,12 @@ want a filename like `0001-description-of-my-change.patch`, and the first letter does not have to be a dot. Leaving it empty would not add any suffix. +--no-binary:: + Don't output contents of changes in binary files, just take note + that they differ. Note that this disable the patch to be properly + applied. By default the contents of changes in those files are + encoded in the patch. + CONFIGURATION ------------- You can specify extra mail header lines to be added to each message @@ -168,38 +174,54 @@ and file suffix, and number patches when outputting more than one. subjectprefix = CHANGE suffix = .txt numbered = auto + cc = <email> ------------ EXAMPLES -------- -git-format-patch -k --stdout R1..R2 | git-am -3 -k:: - Extract commits between revisions R1 and R2, and apply - them on top of the current branch using `git-am` to - cherry-pick them. - -git-format-patch origin:: - Extract all commits which are in the current branch but - not in the origin branch. For each commit a separate file - is created in the current directory. - -git-format-patch \--root origin:: - Extract all commits that lead to 'origin' since the - inception of the project. - -git-format-patch -M -B origin:: - The same as the previous one. Additionally, it detects - and handles renames and complete rewrites intelligently to - produce a renaming patch. A renaming patch reduces the - amount of text output, and generally makes it easier to - review it. Note that the "patch" program does not - understand renaming patches, so use it only when you know - the recipient uses git to apply your patch. - -git-format-patch -3:: - Extract three topmost commits from the current branch - and format them as e-mailable patches. +* Extract commits between revisions R1 and R2, and apply them on top of +the current branch using `git-am` to cherry-pick them: ++ +------------ +$ git format-patch -k --stdout R1..R2 | git-am -3 -k +------------ + +* Extract all commits which are in the current branch but not in the +origin branch: ++ +------------ +$ git format-patch origin +------------ ++ +For each commit a separate file is created in the current directory. + +* Extract all commits that lead to 'origin' since the inception of the +project: ++ +------------ +$ git format-patch \--root origin +------------ + +* The same as the previous one: ++ +------------ +$ git format-patch -M -B origin +------------ ++ +Additionally, it detects and handles renames and complete rewrites +intelligently to produce a renaming patch. A renaming patch reduces +the amount of text output, and generally makes it easier to review it. +Note that the "patch" program does not understand renaming patches, so +use it only when you know the recipient uses git to apply your patch. + +* Extract three topmost commits from the current branch and format them +as e-mailable patches: ++ +------------ +$ git format-patch -3 +------------ See Also -------- diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index be2ae53b90..bfbba9e235 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -82,28 +82,75 @@ man.viewer ~~~~~~~~~~ The 'man.viewer' config variable will be checked if the 'man' format -is chosen. Only the following values are currently supported: +is chosen. The following values are currently supported: * "man": use the 'man' program as usual, * "woman": use 'emacsclient' to launch the "woman" mode in emacs (this only works starting with emacsclient versions 22), -* "konqueror": use a man KIO slave in konqueror. +* "konqueror": use 'kfmclient' to open the man page in a new konqueror +tab (see 'Note about konqueror' below). -Multiple values may be given to this configuration variable. Their -corresponding programs will be tried in the order listed in the -configuration file. +Values for other tools can be used if there is a corresponding +'man.<tool>.cmd' configuration entry (see below). + +Multiple values may be given to the 'man.viewer' configuration +variable. Their corresponding programs will be tried in the order +listed in the configuration file. For example, this configuration: +------------------------------------------------ [man] viewer = konqueror viewer = woman +------------------------------------------------ will try to use konqueror first. But this may fail (for example if DISPLAY is not set) and in that case emacs' woman mode will be tried. If everything fails the 'man' program will be tried anyway. +man.<tool>.path +~~~~~~~~~~~~~~~ + +You can explicitly provide a full path to your preferred man viewer by +setting the configuration variable 'man.<tool>.path'. For example, you +can configure the absolute path to konqueror by setting +'man.konqueror.path'. Otherwise, 'git help' assumes the tool is +available in PATH. + +man.<tool>.cmd +~~~~~~~~~~~~~~ + +When the man viewer, specified by the 'man.viewer' configuration +variables, is not among the supported ones, then the corresponding +'man.<tool>.cmd' configuration variable will be looked up. If this +variable exists then the specified tool will be treated as a custom +command and a shell eval will be used to run the command with the man +page passed as arguments. + +Note about konqueror +~~~~~~~~~~~~~~~~~~~~ + +When 'konqueror' is specified in the 'man.viewer' configuration +variable, we launch 'kfmclient' to try to open the man page on an +already opened konqueror in a new tab if possible. + +For consistency, we also try such a trick if 'man.konqueror.path' is +set to something like 'A_PATH_TO/konqueror'. That means we will try to +launch 'A_PATH_TO/kfmclient' instead. + +If you really want to use 'konqueror', then you can use something like +the following: + +------------------------------------------------ + [man] + viewer = konq + + [man "konq"] + cmd = A_PATH_TO/konqueror +------------------------------------------------ + Note about git config --global ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index c136b10692..ef1f055c85 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -9,7 +9,7 @@ git-merge - Join two or more development histories together SYNOPSIS -------- [verse] -'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]... +'git-merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... [-m <msg>] <remote> <remote>... 'git-merge' <msg> HEAD <remote>... @@ -46,18 +46,7 @@ linkgit:git-reset[1]. CONFIGURATION ------------- - -merge.summary:: - Whether to include summaries of merged commits in newly - created merge commit. False by default. - -merge.verbosity:: - Controls the amount of output shown by the recursive merge - strategy. Level 0 outputs nothing except a final error - message if conflicts were detected. Level 1 outputs only - conflicts, 2 outputs conflicts and file changes. Level 5 and - above outputs debugging information. The default is level 2. - Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable. +include::merge-config.txt[] branch.<name>.mergeoptions:: Sets default options for merging into branch <name>. The syntax and diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index f92bb8cfa0..3178bc44ca 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -18,12 +18,15 @@ git-prune. See the section "NOTES", below. This runs `git-fsck --unreachable` using all the refs available in `$GIT_DIR/refs`, optionally with additional set of -objects specified on the command line, and prunes all +objects specified on the command line, and prunes all unpacked objects unreachable from any of these head objects from the object database. In addition, it prunes the unpacked objects that are also found in packs by running `git prune-packed`. +Note that unreachable, packed objects will remain. If this is +not desired, see linkgit:git-repack[1]. + OPTIONS ------- diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 3405ca09e8..66304f0255 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -111,40 +111,58 @@ rules apply: EXAMPLES -------- -git pull, git pull origin:: - Update the remote-tracking branches for the repository - you cloned from, then merge one of them into your - current branch. Normally the branch merged in is - the HEAD of the remote repository, but the choice is - determined by the branch.<name>.remote and - branch.<name>.merge options; see linkgit:git-config[1] - for details. - -git pull origin next:: - Merge into the current branch the remote branch `next`; - leaves a copy of `next` temporarily in FETCH_HEAD, but - does not update any remote-tracking branches. - -git pull . fixes enhancements:: - Bundle local branch `fixes` and `enhancements` on top of - the current branch, making an Octopus merge. This `git pull .` - syntax is equivalent to `git merge`. - -git pull -s ours . obsolete:: - Merge local branch `obsolete` into the current branch, - using `ours` merge strategy. - -git pull --no-commit . maint:: - Merge local branch `maint` into the current branch, but - do not make a commit automatically. This can be used - when you want to include further changes to the merge, - or want to write your own merge commit message. +* Update the remote-tracking branches for the repository + you cloned from, then merge one of them into your + current branch: ++ +------------------------------------------------ +$ git pull, git pull origin +------------------------------------------------ ++ +Normally the branch merged in is the HEAD of the remote repository, +but the choice is determined by the branch.<name>.remote and +branch.<name>.merge options; see linkgit:git-config[1] for details. + +* Merge into the current branch the remote branch `next`: ++ +------------------------------------------------ +$ git pull origin next +------------------------------------------------ ++ +This leaves a copy of `next` temporarily in FETCH_HEAD, but +does not update any remote-tracking branches. + +* Bundle local branch `fixes` and `enhancements` on top of + the current branch, making an Octopus merge: ++ +------------------------------------------------ +$ git pull . fixes enhancements +------------------------------------------------ ++ +This `git pull .` syntax is equivalent to `git merge`. + +* Merge local branch `obsolete` into the current branch, using `ours` + merge strategy: ++ +------------------------------------------------ +$ git pull -s ours . obsolete +------------------------------------------------ + +* Merge local branch `maint` into the current branch, but do not make + a commit automatically: ++ +------------------------------------------------ +$ git pull --no-commit . maint +------------------------------------------------ ++ +This can be used when you want to include further changes to the +merge, or want to write your own merge commit message. + You should refrain from abusing this option to sneak substantial changes into a merge commit. Small fixups like bumping release/version name would be acceptable. -Command line pull of multiple branches from one repository:: +* Command line pull of multiple branches from one repository: + ------------------------------------------------ $ git checkout master @@ -152,12 +170,12 @@ $ git fetch origin +pu:pu maint:tmp $ git pull . tmp ------------------------------------------------ + -This updates (or creates, as necessary) branches `pu` and `tmp` -in the local repository by fetching from the branches -(respectively) `pu` and `maint` from the remote repository. +This updates (or creates, as necessary) branches `pu` and `tmp` in +the local repository by fetching from the branches (respectively) +`pu` and `maint` from the remote repository. + -The `pu` branch will be updated even if it is does not -fast-forward; the others will not be. +The `pu` branch will be updated even if it is does not fast-forward; +the others will not be. + The final command then merges the newly fetched `tmp` into master. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 0585949137..f06d94e318 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -70,7 +70,9 @@ the remote repository. be mirrored to the remote repository. Newly created local refs will be pushed to the remote end, locally updated refs will be force updated on the remote end, and deleted refs - will be removed from the remote end. + will be removed from the remote end. This is the default + if the configuration option `remote.<remote>.mirror` is + set. \--dry-run:: Do everything except actually send the updates. diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 2cbd1f764b..b20e851973 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -47,9 +47,11 @@ With `-m <master>` option, `$GIT_DIR/remotes/<name>/HEAD` is set up to point at remote's `<master>` branch instead of whatever branch the `HEAD` at the remote repository actually points at. + -In mirror mode, enabled with `--mirror`, the refs will not be stored +In mirror mode, enabled with `\--mirror`, the refs will not be stored in the 'refs/remotes/' namespace, but in 'refs/heads/'. This option -only makes sense in bare repositories. +only makes sense in bare repositories. If a remote uses mirror +mode, furthermore, `git push` will always behave as if `\--mirror` +was passed. 'rm':: diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 110e7ba71f..69599ffb67 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -347,7 +347,7 @@ Each line of options has this format: * Use `*` to mean that this option should not be listed in the usage generated for the `-h` argument. It's shown for `--help-all` as - documented in linkgit:gitcli[5]. + documented in linkgit:gitcli[7]. * Use `!` to not make the corresponding negated long option available. @@ -378,6 +378,31 @@ C? option C with an optional argument" eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?` ------------ +EXAMPLES +-------- + +* Print the object name of the current commit: ++ +------------ +$ git rev-parse --verify HEAD +------------ + +* Print the commit object name from the revision in the $REV shell variable: ++ +------------ +$ git rev-parse --verify $REV +------------ ++ +This will error out if $REV is empty or not a valid revision. + +* Same as above: ++ +------------ +$ git rev-parse --default master --verify $REV +------------ ++ +but if $REV is empty, the commit object name from master will be printed. + Author ------ diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 93e20f7752..13ceabbcc8 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -7,7 +7,7 @@ git-revert - Revert an existing commit SYNOPSIS -------- -'git-revert' [--edit | --no-edit] [-n] [-m parent-number] <commit> +'git-revert' [--edit | --no-edit] [-n] [-m parent-number] [-s] <commit> DESCRIPTION ----------- @@ -51,6 +51,9 @@ OPTIONS This is useful when reverting more than one commits' effect to your working tree in a row. +-s|--signoff:: + Add Signed-off-by line at the end of the commit message. + Author ------ diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 6ffd896fbc..0668f295ee 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -11,7 +11,8 @@ SYNOPSIS [verse] 'git-submodule' [--quiet] add [-b branch] [--] <repository> [<path>] 'git-submodule' [--quiet] status [--cached] [--] [<path>...] -'git-submodule' [--quiet] [init|update] [--] [<path>...] +'git-submodule' [--quiet] init [--] [<path>...] +'git-submodule' [--quiet] update [--init] [--] [<path>...] 'git-submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] @@ -47,6 +48,10 @@ update:: Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. This will make the submodules HEAD be detached. ++ +If the submodule is not yet initialized, and you just want to use the +setting as stored in .gitmodules, you can automatically initialize the +submodule with the --init option. summary:: Show commit summary between the given commit (defaults to HEAD) and diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index bec9accc89..3eae1ebb7d 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -166,11 +166,18 @@ environment). This command has the same behaviour. Any other arguments are passed directly to `git log' 'blame':: - Show what revision and author last modified each line of a file. This is - identical to `git blame', but SVN revision numbers are shown instead of git - commit hashes. + Show what revision and author last modified each line of a file. The + output of this mode is format-compatible with the output of + `svn blame' by default. Like the SVN blame command, + local uncommitted changes in the working copy are ignored; + the version of the file in the HEAD revision is annotated. Unknown + arguments are passed directly to git-blame. + -All arguments are passed directly to `git blame'. +--git-format;; + Produce output in the same format as `git blame', but with + SVN revision numbers instead of git commit hashes. In this mode, + changes that haven't been committed to SVN (including local + working-copy edits) are shown as revision 0. -- 'find-rev':: @@ -188,6 +195,12 @@ All arguments are passed directly to `git blame'. commit. All merging is assumed to have taken place independently of git-svn functions. +'create-ignore':: + Recursively finds the svn:ignore property on directories and + creates matching .gitignore files. The resulting files are staged to + be committed, but are not committed. Use -r/--revision to refer to a + specfic revision. + 'show-ignore':: Recursively finds and lists the svn:ignore property on directories. The output is suitable for appending to @@ -210,6 +223,19 @@ All arguments are passed directly to `git blame'. argument. Use the --url option to output only the value of the 'URL:' field. +'proplist':: + Lists the properties stored in the Subversion repository about a + given file or directory. Use -r/--revision to refer to a specific + Subversion revision. + +'propget':: + Gets the Subversion property given as the first argument, for a + file. A specific revision can be specified with -r/--revision. + +'show-externals':: + Shows the Subversion externals. Use -r/--revision to specify a + specific revision. + -- OPTIONS diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index ddbae5b194..5ba0b9f1c9 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -20,7 +20,7 @@ The following browsers (or commands) are currently supported: * firefox (this is the default under X Window when not using KDE) * iceweasel -* konqueror (this is the default under KDE) +* konqueror (this is the default under KDE, see 'Note about konqueror' below) * w3m (this is the default outside graphical environments) * links * lynx @@ -71,6 +71,28 @@ variable exists then "git web--browse" will treat the specified tool as a custom command and will use a shell eval to run the command with the URLs passed as arguments. +Note about konqueror +-------------------- + +When 'konqueror' is specified by the a command line option or a +configuration variable, we launch 'kfmclient' to try to open the HTML +man page on an already opened konqueror in a new tab if possible. + +For consistency, we also try such a trick if 'browser.konqueror.path' is +set to something like 'A_PATH_TO/konqueror'. That means we will try to +launch 'A_PATH_TO/kfmclient' instead. + +If you really want to use 'konqueror', then you can use something like +the following: + +------------------------------------------------ + [web] + browser = konq + + [browser "konq"] + cmd = A_PATH_TO/konqueror +------------------------------------------------ + Note about git config --global ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git.txt b/Documentation/git.txt index 6f445b1e3b..adcd3e00b2 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -364,7 +364,7 @@ File/Directory Structure Please see the link:repository-layout.html[repository layout] document. -Read link:hooks.html[hooks] for more details about each hook. +Read linkgit:githooks[5][hooks] for more details about each hook. Higher level SCMs may provide and manage additional information in the `$GIT_DIR`. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 7ee5ce386f..835cb05f96 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -1,4 +1,4 @@ -gitcli(5) +gitcli(7) ========= NAME diff --git a/Documentation/hooks.txt b/Documentation/githooks.txt index 1283ab4daa..53747febd2 100644 --- a/Documentation/hooks.txt +++ b/Documentation/githooks.txt @@ -1,5 +1,17 @@ -Hooks used by git -================= +githooks(5) +=========== + +NAME +---- +githooks - Hooks used by git + +SYNOPSIS +-------- +$GIT_DIR/hooks/* + + +DESCRIPTION +----------- Hooks are little scripts you can place in `$GIT_DIR/hooks` directory to trigger action at certain points. When @@ -137,7 +149,8 @@ post-merge This hook is invoked by `git-merge`, which happens when a `git pull` is done on a local repository. The hook takes a single parameter, a status flag specifying whether or not the merge being done was a squash merge. -This hook cannot affect the outcome of `git-merge`. +This hook cannot affect the outcome of `git-merge` and is not executed, +if the merge failed due to conflicts. This hook can be used in conjunction with a corresponding pre-commit hook to save and restore any form of metadata associated with the working tree @@ -284,3 +297,7 @@ pre-auto-gc This hook is invoked by `git-gc --auto`. It takes no parameter, and exiting with non-zero status from this script causes the `git-gc --auto` to abort. + +GIT +--- +Part of the linkgit:git[7] suite diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt new file mode 100644 index 0000000000..48ce747cf4 --- /dev/null +++ b/Documentation/merge-config.txt @@ -0,0 +1,40 @@ +merge.stat:: + Whether to print the diffstat berween ORIG_HEAD and merge result + at the end of the merge. True by default. + +merge.log:: + Whether to include summaries of merged commits in newly created + merge commit messages. False by default. + +merge.renameLimit:: + The number of files to consider when performing rename detection + during a merge; if not specified, defaults to the value of + diff.renameLimit. + +merge.tool:: + Controls which merge resolution program is used by + linkgit:git-mergetool[1]. Valid built-in values are: "kdiff3", + "tkdiff", "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", and + "opendiff". Any other value is treated is custom merge tool + and there must be a corresponing mergetool.<tool>.cmd option. + +merge.verbosity:: + Controls the amount of output shown by the recursive merge + strategy. Level 0 outputs nothing except a final error + message if conflicts were detected. Level 1 outputs only + conflicts, 2 outputs conflicts and file changes. Level 5 and + above outputs debugging information. The default is level 2. + Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable. + +merge.<driver>.name:: + Defines a human readable name for a custom low-level + merge driver. See linkgit:gitattributes[5] for details. + +merge.<driver>.driver:: + Defines the command that implements a custom low-level + merge driver. See linkgit:gitattributes[5] for details. + +merge.<driver>.recursive:: + Names a low-level merge driver to be used when + performing an internal merge between common ancestors. + See linkgit:gitattributes[5] for details. diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 9f1fc82550..f37a776489 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -1,10 +1,23 @@ ---summary:: +--stat:: Show a diffstat at the end of the merge. The diffstat is also - controlled by the configuration option merge.diffstat. + controlled by the configuration option merge.stat. --n, \--no-summary:: +-n, \--no-stat:: Do not show diffstat at the end of the merge. +--summary, \--no-summary:: + Synonyms to --stat and --no-stat; these are deprecated and will be + removed in the future. + +--log:: + In addition to branch names, populate the log message with + one-line descriptions from the actual commits that are being + merged. + +--no-log:: + Do not list one-line descriptions from the actual commits being + merged. + --no-commit:: Perform the merge but pretend the merge failed and do not autocommit, to give the user a chance to inspect and diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt index 6939130094..7fd187be8a 100644 --- a/Documentation/repository-layout.txt +++ b/Documentation/repository-layout.txt @@ -3,7 +3,10 @@ git repository layout You may find these things in your git repository (`.git` directory for a repository associated with your working tree, or -`'project'.git` directory for a public 'bare' repository). +`'project'.git` directory for a public 'bare' repository. It is +also possible to have a working tree where `.git` is a plain +ascii file containing `gitdir: <path>`, i.e. the path to the +real git repository). objects:: Object store associated with this repository. Usually @@ -121,7 +124,7 @@ hooks:: commands. A handful of sample hooks are installed when `git init` is run, but all of them are disabled by default. To enable, they need to be made executable. - Read link:hooks.html[hooks] for more details about + Read linkgit:githooks[5][hooks] for more details about each hook. index:: diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 86b91a53e5..e2db850150 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1881,7 +1881,7 @@ $ chmod a+x hooks/post-update (For an explanation of the last two lines, see linkgit:git-update-server-info[1], and the documentation -link:hooks.html[Hooks used by git].) +linkgit:githooks[5][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 command line like: |