diff options
Diffstat (limited to 'Documentation')
32 files changed, 426 insertions, 190 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index b06275726d..76a15ff520 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -44,6 +44,11 @@ INSTALL?=install RM ?= rm -f DOC_REF = origin/man +infodir?=$(prefix)/share/info +MAKEINFO=makeinfo +INSTALL_INFO=install-info +DOCBOOK2X_TEXI=docbook2x-texi + -include ../config.mak.autogen -include ../config.mak @@ -67,6 +72,8 @@ man1: $(DOC_MAN1) man5: $(DOC_MAN5) man7: $(DOC_MAN7) +info: git.info + install: man $(INSTALL) -d -m755 $(DESTDIR)$(man1dir) $(INSTALL) -d -m755 $(DESTDIR)$(man5dir) @@ -75,6 +82,14 @@ install: man $(INSTALL) -m644 $(DOC_MAN5) $(DESTDIR)$(man5dir) $(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir) +install-info: info + $(INSTALL) -d -m755 $(DESTDIR)$(infodir) + $(INSTALL) -m644 git.info $(DESTDIR)$(infodir) + if test -r $(DESTDIR)$(infodir)/dir; then \ + $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) git.info ;\ + else \ + echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \ + fi ../GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE $(MAKE) -C ../ GIT-VERSION-FILE @@ -110,7 +125,7 @@ cmd-list.made: cmd-list.perl $(MAN1_TXT) git.7 git.html: git.txt core-intro.txt clean: - $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 howto-index.txt howto/*.html doc.dep + $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.texi *.texi+ howto-index.txt howto/*.html doc.dep $(RM) $(cmds_txt) *.made %.html : %.txt @@ -120,6 +135,7 @@ clean: mv $@+ $@ %.1 %.5 %.7 : %.xml + $(RM) $@ xmlto -m callouts.xsl man $< %.xml : %.txt @@ -131,12 +147,19 @@ clean: user-manual.xml: user-manual.txt user-manual.conf $(ASCIIDOC) -b docbook -d book $< -XSLT = http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl +XSLT = docbook.xsl XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css user-manual.html: user-manual.xml xsltproc $(XSLTOPTS) -o $@ $(XSLT) $< +git.info: user-manual.xml + $(RM) $@ $*.texi $*.texi+ + $(DOCBOOK2X_TEXI) user-manual.xml --to-stdout >$*.texi+ + perl fix-texi.perl <$*.texi+ >$*.texi + $(MAKEINFO) --no-split $*.texi + $(RM) $*.texi $*.texi+ + howto-index.txt: howto-index.sh $(wildcard howto/*.txt) $(RM) $@+ $@ sh ./howto-index.sh $(wildcard howto/*.txt) >$@+ diff --git a/Documentation/RelNotes-1.5.3.txt b/Documentation/RelNotes-1.5.3.txt index 896ff1d95a..21bb1fc6f2 100644 --- a/Documentation/RelNotes-1.5.3.txt +++ b/Documentation/RelNotes-1.5.3.txt @@ -32,23 +32,34 @@ Updates since v1.5.2 - "git rebase" learned an "interactive" mode that let you pick and reorder which commits to rebuild. - - "git fsck" can save its findings in $GIT_DIR/lost-found, - without a separate invocation of "git lost-found" command. + - "git fsck" can save its findings in $GIT_DIR/lost-found, without a + separate invocation of "git lost-found" command. The blobs stored by + lost-found are stored in plain format to allow you to grep in them. - $GIT_WORK_TREE environment variable can be used together with $GIT_DIR to work in a subdirectory of a working tree that is not located at "$GIT_DIR/..". + - Giving "--file=<file>" option to "git config" is the same as + running the command with GIT_CONFIG=<file> environment. + - "git log" learned a new option "--follow", to follow renaming history of a single file. - "git-filter-branch" lets you rewrite the revision history of - the current branch, creating a new branch. You can specify a - number of filters to modify the commits, files and trees. + specified branches. You can specify a number of filters to + modify the commits, files and trees. - "git-cvsserver" learned new options (--base-path, --export-all, --strict-paths) inspired by git-daemon. + - "git daemon --base-path-relaxed" can help migrating a repository URL + that did not use to use --base-path to use --base-path. + + - "git-commit" can use "-t templatefile" option and commit.template + configuration variable to prime the commit message given to you in the + editor. + - "git-submodule" command helps you manage the projects from the superproject that contain them. @@ -105,9 +116,33 @@ Updates since v1.5.2 * Updated behavior of existing commands. + - "gitweb" can offer multiple snapshot formats. + + ***NOTE*** Unfortunately, this changes the format of the + $feature{snapshot}{default} entry in the per-site + configuration file 'gitweb_config.perl'. It used to be a + three-element tuple that describe a single format; with the + new configuration item format, you only have to say the name + of the format ('tgz', 'tbz2' or 'zip'). Please update the + your configuration file accordingly. + + - "git diff" (but not the plumbing level "git diff-tree") now + recursively descends into trees by default. + + - The editor to use with many interactive commands can be + overridden with GIT_EDITOR environment variable, or if it + does not exist, with core.editor configuration variable. As + before, if you have neither, environment variables VISUAL + and EDITOR are consulted in this order, and then finally we + fall back on "vi". + - "git rm --cached" does not complain when removing a newly added file from the index anymore. + - Options to "git log" to affect how --grep/--author options look for + given strings now have shorter abbreviations. -i is for ignore case, + and -E is for extended regexp. + - "git svn dcommit" retains local merge information. - "git config" to set values also honors type flags like --bool @@ -139,6 +174,9 @@ Updates since v1.5.2 - The diffstat given after a merge (or a pull) honors the color.diff configuration. + - "git commit --amend" is now compatible with various message source + options such as -m/-C/-c/-F. + - "git-apply --whitespace=strip" removes blank lines added at the end of the file. @@ -189,6 +227,10 @@ Updates since v1.5.2 git-fast-import (also in contrib). The man page and p4 rpm have been removed as well. + - "git mailinfo" (hence "am") now tries to see if the message + is in utf-8 first, instead of assuming iso-8859-1, if + incoming e-mail does not say what encoding it is in. + * Builds - old-style function definitions (most notably, a function @@ -232,6 +274,6 @@ this release, unless otherwise noted. -- exec >/var/tmp/1 -O=v1.5.3-rc2 +O=v1.5.3-rc4 echo O=`git describe refs/heads/master` git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index a46bf6ce70..17379f0576 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -64,11 +64,11 @@ of lines before or after the line given by <start>. assigns blame to the lines that were moved down (i.e. A) to the child commit. With this option, both groups of lines are blamed on the parent. - - <num> is optional but it is the lower bound on the number of - alphanumeric characters that git must detect as moving - within a file for it to associate those lines with the parent - commit. ++ +<num> is optional but it is the lower bound on the number of +alphanumeric characters that git must detect as moving +within a file for it to associate those lines with the parent +commit. -C|<num>|:: In addition to `-M`, detect lines copied from other @@ -77,11 +77,11 @@ of lines before or after the line given by <start>. around across files. When this option is given twice, the command looks for copies from all other files in the parent for the commit that creates the file in addition. - - <num> is optional but it is the lower bound on the number of - alphanumeric characters that git must detect as moving - between files for it to associate those lines with the parent - commit. ++ +<num> is optional but it is the lower bound on the number of +alphanumeric characters that git must detect as moving +between files for it to associate those lines with the parent +commit. -h, --help:: Show help message. diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 2143995ece..4ee76eaf99 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -68,6 +68,8 @@ for my $cat (qw(ancillaryinterrogators } } +# The following list is sorted with "sort -d" to make it easier +# to find entry in the resulting git.html manual page. __DATA__ git-add mainporcelain git-am mainporcelain @@ -80,9 +82,9 @@ git-blame ancillaryinterrogators git-branch mainporcelain git-bundle mainporcelain git-cat-file plumbinginterrogators -git-checkout-index plumbingmanipulators -git-checkout mainporcelain git-check-attr purehelpers +git-checkout mainporcelain +git-checkout-index plumbingmanipulators git-check-ref-format purehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain @@ -91,6 +93,7 @@ git-clean mainporcelain git-clone mainporcelain git-commit mainporcelain git-commit-tree plumbingmanipulators +git-config ancillarymanipulators git-convert-objects ancillarymanipulators git-count-objects ancillaryinterrogators git-cvsexportcommit foreignscminterface @@ -98,9 +101,9 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describe mainporcelain +git-diff mainporcelain git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators -git-diff mainporcelain git-diff-tree plumbinginterrogators git-fast-import ancillarymanipulators git-fetch mainporcelain @@ -130,13 +133,13 @@ git-ls-remote plumbinginterrogators git-ls-tree plumbinginterrogators git-mailinfo purehelpers git-mailsplit purehelpers +git-merge mainporcelain git-merge-base plumbinginterrogators git-merge-file plumbingmanipulators git-merge-index plumbingmanipulators -git-merge mainporcelain git-merge-one-file purehelpers -git-merge-tree ancillaryinterrogators git-mergetool ancillarymanipulators +git-merge-tree ancillaryinterrogators git-mktag plumbingmanipulators git-mktree plumbingmanipulators git-mv mainporcelain @@ -157,9 +160,8 @@ git-rebase mainporcelain git-receive-pack synchelpers git-reflog ancillarymanipulators git-relink ancillarymanipulators -git-repack ancillarymanipulators -git-config ancillarymanipulators git-remote ancillarymanipulators +git-repack ancillarymanipulators git-request-pull foreignscminterface git-rerere ancillaryinterrogators git-reset mainporcelain diff --git a/Documentation/config.txt b/Documentation/config.txt index a850d55bf6..de9e72b562 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -101,7 +101,7 @@ Example # Proxy settings [core] - gitProxy="ssh" for "ssh://kernel.org/" + gitProxy="ssh" for "kernel.org" gitProxy=default-proxy ; for the rest Variables @@ -286,8 +286,8 @@ core.editor:: messages by lauching an editor uses the value of this variable when it is set, and the environment variable `GIT_EDITOR` is not set. The order of preference is - `GIT_EDITOR` environment, `core.editor`, `EDITOR` and - `VISUAL` environment variables and then finally `vi`. + `GIT_EDITOR` environment, `core.editor`, `VISUAL` and + `EDITOR` environment variables and then finally `vi`. core.pager:: The command that git will use to paginate output. Can be overridden @@ -393,6 +393,9 @@ color.status.<slot>:: or `untracked` (files which are not tracked by git). The values of these variables may be specified as in color.branch.<slot>. +commit.template:: + Specify a file to use as the template for new commit messages. + diff.renameLimit:: The number of files to consider when performing the copy/rename detection; equivalent to the git diff option '-l'. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 3d2b9d0a06..228ccaf10a 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -4,6 +4,13 @@ -u:: Synonym for "-p". +-U<n>:: + Shorthand for "--unified=<n>". + +--unified=<n>:: + Generate diffs with <n> lines of context instead of + the usual three. Implies "-p". + --raw:: Generate the raw format. @@ -36,7 +43,9 @@ Synonym for "-p --stat". -z:: - \0 line termination on output + NUL-line termination on output. This affects the --raw + output field terminator. Also output from commands such + as "git-log" will be delimited with NUL between commits. --name-only:: Show only names of changed files. diff --git a/Documentation/docbook.xsl b/Documentation/docbook.xsl new file mode 100644 index 0000000000..9a6912c641 --- /dev/null +++ b/Documentation/docbook.xsl @@ -0,0 +1,5 @@ +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0'> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/> + <xsl:output method="html" encoding="UTF-8" indent="no" /> +</xsl:stylesheet> diff --git a/Documentation/fix-texi.perl b/Documentation/fix-texi.perl new file mode 100755 index 0000000000..ff7d78f620 --- /dev/null +++ b/Documentation/fix-texi.perl @@ -0,0 +1,15 @@ +#!/usr/bin/perl -w + +while (<>) { + if (/^\@setfilename/) { + $_ = "\@setfilename git.info\n"; + } elsif (/^\@direntry/) { + print '@dircategory Development +@direntry +* Git: (git). A fast distributed revision control system +@end direntry +'; } + unless (/^\@direntry/../^\@end direntry/) { + print; + } +} diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 76d2b05854..4af3a9b0d7 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -3,7 +3,7 @@ git-add(1) NAME ---- -git-add - Add file contents to the changeset to be committed next +git-add - Add file contents to the index SYNOPSIS -------- @@ -11,24 +11,27 @@ SYNOPSIS DESCRIPTION ----------- -All the changed file contents to be committed together in a single set -of changes must be "added" with the 'add' command before using the -'commit' command. This is not only for adding new files. Even modified -files must be added to the set of changes about to be committed. - -This command can be performed multiple times before a commit. The added -content corresponds to the state of specified file(s) at the time the -'add' command is used. This means the 'commit' command will not consider -subsequent changes to already added content if it is not added again before -the commit. - -The 'git status' command can be used to obtain a summary of what is included -for the next commit. - -This command can be used to add ignored files with `-f` (force) -option, but they have to be -explicitly and exactly specified from the command line. File globbing -and recursive behaviour do not add ignored files. +This command adds the current content of new or modified files to the +index, thus staging that content for inclusion in the next commit. + +The "index" holds a snapshot of the content of the working tree, and it +is this snapshot that is taken as the contents of the next commit. Thus +after making any changes to the working directory, and before running +the commit command, you must use the 'add' command to add any new or +modified files to the index. + +This command can be performed multiple times before a commit. It only +adds the content of the specified file(s) at the time the add command is +run; if you want subsequent changes included in the next commit, then +you must run 'git add' again to add the new content to the index. + +The 'git status' command can be used to obtain a summary of which +files have changes that are staged for the next commit. + +The 'add' command can be used to add ignored files with `-f` (force) +option, but they have to be explicitly and exactly specified from the +command line. File globbing and recursive behaviour do not add ignored +files. Please see gitlink:git-commit[1] for alternative ways to add content to a commit. diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index bc6aa88417..33bc31b0d4 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -134,8 +134,8 @@ $ git branch -d -r origin/todo origin/html origin/man <1> $ git branch -D test <2> ------------ + -<1> delete remote-tracking branches "todo", "html", "man" -<2> delete "test" branch even if the "master" branch does not have all +<1> Delete remote-tracking branches "todo", "html", "man" +<2> Delete "test" branch even if the "master" branch does not have all commits from test branch. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index a0a10e3e26..227f092e26 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -9,7 +9,8 @@ git-clone - Clone a repository into a new directory SYNOPSIS -------- [verse] -'git-clone' [--template=<template_directory>] [-l [-s]] [-q] [-n] [--bare] +'git-clone' [--template=<template_directory>] + [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [-o <name>] [-u <upload-pack>] [--reference <repository>] [--depth <depth>] <repository> [<directory>] @@ -40,8 +41,19 @@ OPTIONS this flag bypasses normal "git aware" transport mechanism and clones the repository by making a copy of HEAD and everything under objects and refs directories. - The files under .git/objects/ directory are hardlinked - to save space when possible. + The files under `.git/objects/` directory are hardlinked + to save space when possible. This is now the default when + the source repository is specified with `/path/to/repo` + syntax, so it essentially is a no-op option. To force + copying instead of hardlinking (which may be desirable + if you are trying to make a back-up of your repository), + but still avoid the usual "git aware" transport + mechanism, `--no-hardlinks` can be used. + +--no-hardlinks:: + Optimize the cloning process from a repository on a + local filesystem by copying files under `.git/objects` + directory. --shared:: -s:: diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 8e0e7e2d04..e54fb12103 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -15,26 +15,27 @@ SYNOPSIS DESCRIPTION ----------- -Use 'git commit' when you want to record your changes into the repository -along with a log message describing what the commit is about. All changes -to be committed must be explicitly identified using one of the following -methods: +Use 'git commit' to store the current contents of the index in a new +commit along with a log message describing the changes you have made. + +The content to be added can be specified in several ways: 1. by using gitlink:git-add[1] to incrementally "add" changes to the - next commit before using the 'commit' command (Note: even modified + index before using the 'commit' command (Note: even modified files must be "added"); -2. by using gitlink:git-rm[1] to identify content removal for the next - commit, again before using the 'commit' command; +2. by using gitlink:git-rm[1] to remove files from the working tree + and the index, again before using the 'commit' command; -3. by directly listing files containing changes to be committed as arguments - to the 'commit' command, in which cases only those files alone will be - considered for the commit; +3. by listing files as arguments to the 'commit' command, in which + case the commit will ignore changes staged in the index, and instead + record the current content of the listed files; -4. by using the -a switch with the 'commit' command to automatically "add" - changes from all known files i.e. files that have already been committed - before, and to automatically "rm" files that have been - removed from the working tree, and perform the actual commit. +4. by using the -a switch with the 'commit' command to automatically + "add" changes from all known files (i.e. all files that are already + listed in the index) and to automatically "rm" files in the index + that have been removed from the working tree, and then perform the + actual commit; 5. by using the --interactive switch with the 'commit' command to decide one by one which files should be part of the commit, before finalizing the @@ -74,6 +75,13 @@ OPTIONS -m <msg>|--message=<msg>:: Use the given <msg> as the commit message. +-t <file>|--template=<file>:: + Use the contents of the given file as the initial version + of the commit message. The editor is invoked and you can + make subsequent changes. If a message is specified using + the `-m` or `-F` options, this option has no effect. This + overrides the `commit.template` configuration variable. + -s|--signoff:: Add Signed-off-by line at the end of the commit message. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 5f66a7fcd5..c3dffffe32 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,17 +9,17 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git-config' [--system | --global] [type] [-z|--null] name [value [value_regex]] -'git-config' [--system | --global] [type] --add name value -'git-config' [--system | --global] [type] --replace-all name [value [value_regex]] -'git-config' [--system | --global] [type] [-z|--null] --get name [value_regex] -'git-config' [--system | --global] [type] [-z|--null] --get-all name [value_regex] -'git-config' [--system | --global] [type] [-z|--null] --get-regexp name_regex [value_regex] -'git-config' [--system | --global] --unset name [value_regex] -'git-config' [--system | --global] --unset-all name [value_regex] -'git-config' [--system | --global] --rename-section old_name new_name -'git-config' [--system | --global] --remove-section name -'git-config' [--system | --global] [-z|--null] -l | --list +'git-config' [<file-option>] [type] [-z|--null] name [value [value_regex]] +'git-config' [<file-option>] [type] --add name value +'git-config' [<file-option>] [type] --replace-all name [value [value_regex]] +'git-config' [<file-option>] [type] [-z|--null] --get name [value_regex] +'git-config' [<file-option>] [type] [-z|--null] --get-all name [value_regex] +'git-config' [<file-option>] [type] [-z|--null] --get-regexp name_regex [value_regex] +'git-config' [<file-option>] --unset name [value_regex] +'git-config' [<file-option>] --unset-all name [value_regex] +'git-config' [<file-option>] --rename-section old_name new_name +'git-config' [<file-option>] --remove-section name +'git-config' [<file-option>] [-z|--null] -l | --list DESCRIPTION ----------- @@ -40,10 +40,16 @@ convert the value to the canonical form (simple decimal number for int, a "true" or "false" string for bool). If no type specifier is passed, no checks or transformations are performed on the value. +The file-option can be one of '--system', '--global' or '--file' +which specify where the values will be read from or written to. +The default is to assume the config file of the current repository, +.git/config unless defined otherwise with GIT_DIR and GIT_CONFIG +(see <<FILES>>). + This command will fail if: -. The .git/config file is invalid, -. Can not write to .git/config, +. The config file is invalid, +. Can not write to the config file, . no section was provided, . the section or key is invalid, . you try to unset an option which does not exist, @@ -93,6 +99,9 @@ rather than from all available files. + See also <<FILES>>. +-f config-file, --file config-file:: + Use the given config file instead of the one specified by GIT_CONFIG. + --remove-section:: Remove the given section from the configuration file. @@ -130,8 +139,8 @@ See also <<FILES>>. FILES ----- -There are three files where git-config will search for configuration -options: +If not set explicitely with '--file', there are three files where +git-config will search for configuration options: .git/config:: Repository specific configuration file. (The filename is @@ -205,9 +214,7 @@ Given a .git/config like this: ; Proxy settings [core] - gitproxy="ssh" for "ssh://kernel.org/" gitproxy="proxy-command" for kernel.org - gitproxy="myprotocol-command" for "my://" gitproxy=default-proxy ; for all the rest you can set the filemode to true with @@ -282,7 +289,7 @@ To actually match only values with an exclamation mark, you have to To add a new proxy, without altering any of the existing ones, use ------------ -% git config core.gitproxy '"proxy" for example.com' +% git config core.gitproxy '"proxy-command" for example.com' ------------ diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 4b30b18b42..f902161c08 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -54,6 +54,12 @@ OPTIONS 'git://example.com/hello.git', `git-daemon` will interpret the path as '/srv/git/hello.git'. +--base-path-relaxed:: + If --base-path is enabled and repo lookup fails, with this option + `git-daemon` will attempt to lookup without prefixing the base path. + This is useful for switching to --base-path usage, while still + allowing the old paths. + --interpolated-path=pathtemplate:: To support virtual hosting, an interpolated path template can be used to dynamically construct alternate paths. The template diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 639b969315..b36e705dd0 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -76,10 +76,10 @@ $ git diff --cached <2> $ git diff HEAD <3> ------------ + -<1> changes in the working tree not yet staged for the next commit. -<2> changes between the index and your last commit; what you +<1> Changes in the working tree not yet staged for the next commit. +<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 +<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:: @@ -90,30 +90,27 @@ $ git diff HEAD -- ./test <2> $ git diff HEAD^ HEAD <3> ------------ + -<1> instead of using the tip of the current branch, compare with the +<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 +<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. +<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 --name-status <2> $ git diff arch/i386 include/asm-i386 <3> ------------ + -<1> show only modification, rename and copy, but not addition +<1> Show only modification, rename and copy, but not addition nor deletion. -<2> show only names and the nature of change, but not actual -diff output. --name-status disables usual patch generation -which in turn also disables recursive behavior, 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. +<2> Show only names and the nature of change, but not actual +diff output. +<3> Limit diff output to named subtrees. Munging the diff output:: + @@ -122,9 +119,9 @@ $ git diff --find-copies-harder -B -C <1> $ git diff -R <2> ------------ + -<1> spend extra cycles to find renames, copies and complete +<1> Spend extra cycles to find renames, copies and complete rewrites (very expensive). -<2> output diff in reverse. +<2> Output diff in reverse. Author diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index eaea82d0a6..915258f410 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -12,7 +12,7 @@ SYNOPSIS [--index-filter <command>] [--parent-filter <command>] [--msg-filter <command>] [--commit-filter <command>] [--tag-name-filter <command>] [--subdirectory-filter <directory>] - [-d <directory>] <new-branch-name> [<rev-list options>...] + [-d <directory>] [-f | --force] [<rev-list options>...] DESCRIPTION ----------- @@ -26,10 +26,9 @@ information) will be preserved. The command takes the new branch name as a mandatory argument and the filters as optional arguments. If you specify no filters, the commits will be recommitted without any changes, which would normally -have no effect and result in the new branch pointing to the same -branch as your current branch. Nevertheless, this may be useful in -the future for compensating for some git bugs or such, therefore -such a usage is permitted. +have no effect. Nevertheless, this may be useful in the future for +compensating for some git bugs or such, therefore such a usage is +permitted. *WARNING*! The rewritten history will have different object names for all the objects and will not converge with the original branch. You will not @@ -38,8 +37,9 @@ original branch. Please do not use this command if you do not know the full implications, and avoid using it anyway, if a simple single commit would suffice to fix your problem. -Always verify that the rewritten version is correct before disposing -the original branch. +Always verify that the rewritten version is correct: The original refs, +if different from the rewritten ones, will be stored in the namespace +'refs/original/'. Note that since this operation is extensively I/O expensive, it might be a good idea to redirect the temporary directory off-disk, e.g. on @@ -142,6 +142,11 @@ definition impossible to preserve signatures at any rate.) does this in the '.git-rewrite/' directory but you can override that choice by this parameter. +-f\|--force:: + `git filter-branch` refuses to start with an existing temporary + directory or when there are already refs starting with + 'refs/original/', unless forced. + <rev-list-options>:: When options are given after the new branch name, they will be passed to gitlink:git-rev-list[1]. Only commits in the resulting @@ -156,14 +161,14 @@ Suppose you want to remove a file (containing confidential information or copyright violation) from all commits: ------------------------------------------------------- -git filter-branch --tree-filter 'rm filename' newbranch +git filter-branch --tree-filter 'rm filename' HEAD ------------------------------------------------------- A significantly faster version: -------------------------------------------------------------------------------- -git filter-branch --index-filter 'git update-index --remove filename' newbranch -------------------------------------------------------------------------------- +-------------------------------------------------------------------------- +git filter-branch --index-filter 'git update-index --remove filename' HEAD +-------------------------------------------------------------------------- Now, you will get the rewritten history saved in the branch 'newbranch' (your current branch is left untouched). @@ -172,25 +177,25 @@ To set a commit (which typically is at the tip of another history) to be the parent of the current initial commit, in order to paste the other history behind the current history: ------------------------------------------------------------------------- -git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' newbranch ------------------------------------------------------------------------- +------------------------------------------------------------------- +git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD +------------------------------------------------------------------- (if the parent string is empty - therefore we are dealing with the initial commit - add graftcommit as a parent). Note that this assumes history with a single root (that is, no merge without common ancestors happened). If this is not the case, use: -------------------------------------------------------------------------------- +-------------------------------------------------------------------------- git filter-branch --parent-filter \ - 'cat; test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>"' newbranch -------------------------------------------------------------------------------- + 'cat; test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>"' HEAD +-------------------------------------------------------------------------- or even simpler: ----------------------------------------------- echo "$commit-id $graft-id" >> .git/info/grafts -git filter-branch newbranch $graft-id.. +git filter-branch $graft-id..HEAD ----------------------------------------------- To remove commits authored by "Darl McBribe" from the history: @@ -208,7 +213,7 @@ git filter-branch --commit-filter ' done; else git commit-tree "$@"; - fi' newbranch + fi' HEAD ------------------------------------------------------------------------------ The shift magic first throws away the tree id and then the -p @@ -238,14 +243,14 @@ A--B-----C To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use: -------------------------------- -git filter-branch ... new-H C..H +git filter-branch ... C..H -------------------------------- To rewrite commits E,F,G,H, use one of these: ---------------------------------------- -git filter-branch ... new-H C..H --not D -git filter-branch ... new-H D..H --not C +git filter-branch ... C..H --not D +git filter-branch ... D..H --not C ---------------------------------------- To move the whole tree into a subdirectory, or remove it from there: @@ -255,7 +260,7 @@ git filter-branch --index-filter \ 'git ls-files -s | sed "s-\t-&newsubdir/-" | GIT_INDEX_FILE=$GIT_INDEX_FILE.new \ git update-index --index-info && - mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' directorymoved + mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD --------------------------------------------------------------- diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 1a432f2319..45c0bee50a 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -65,8 +65,10 @@ index file and all SHA1 references in .git/refs/* as heads. Be chatty. --lost-found:: - Write dangling refs into .git/lost-found/commit/ or - .git/lost-found/other/, depending on type. + Write dangling objects into .git/lost-found/commit/ or + .git/lost-found/other/, depending on type. If the object is + a blob, the contents are written into the file, rather than + its object name. It tests SHA1 and general object sanity, and it does full tracking of the resulting reachability and everything else. It prints out any diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 2c9db98a3c..144bc16ff2 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -107,11 +107,11 @@ pull after you are done and ready. When things cleanly merge, these things happen: -1. the results are updated both in the index file and in your - working tree, -2. index file is written out as a tree, -3. the tree gets committed, and -4. the `HEAD` pointer gets advanced. +1. The results are updated both in the index file and in your + working tree; +2. Index file is written out as a tree; +3. The tree gets committed; and +4. The `HEAD` pointer gets advanced. Because of 2., we require that the original state of the index file to match exactly the current `HEAD` commit; otherwise we diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 74a0da1ed4..0dd9caf867 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -79,7 +79,7 @@ the remote repository. -f, \--force:: Usually, the command refuses to update a remote ref that is - not a descendant of the local ref used to overwrite it. + not an ancestor of the local ref used to overwrite it. This flag disables the check. This can cause the remote repository to lose commits; use it with care. diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 19c5b9bbda..15e3aca9a1 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -63,7 +63,7 @@ $ git commit -a -c ORIG_HEAD <3> <1> This is most often done when you remembered what you just committed is incomplete, or you misspelled your commit message, or both. Leaves working tree as it was before "reset". -<2> make corrections to working tree files. +<2> Make corrections to working tree files. <3> "reset" copies the old head to .git/ORIG_HEAD; redo the commit by starting with its log message. If you do not need to edit the message further, you can give -C option instead. @@ -106,17 +106,17 @@ $ git reset <3> $ git pull git://info.example.com/ nitfol <4> ------------ + -<1> you are happily working on something, and find the changes +<1> You are happily working on something, and find the changes in these files are in good order. You do not want to see them when you run "git diff", because you plan to work on other files and changes with these files are distracting. -<2> somebody asks you to pull, and the changes sounds worthy of merging. -<3> however, you already dirtied the index (i.e. your index does +<2> Somebody asks you to pull, and the changes sounds worthy of merging. +<3> However, you already dirtied the index (i.e. your index does not match the HEAD commit). But you know the pull you are going to make does not affect frotz.c nor filfre.c, so you revert the index changes for these two files. Your changes in working tree remain there. -<4> then you can pull and merge, leaving frotz.c and filfre.c +<4> Then you can pull and merge, leaving frotz.c and filfre.c changes still in the working tree. Undo a merge or pull:: @@ -133,15 +133,15 @@ Fast forward $ git reset --hard ORIG_HEAD <4> ------------ + -<1> try to update from the upstream resulted in a lot of +<1> Try to update from the upstream resulted in a lot of conflicts; you were not ready to spend a lot of time merging right now, so you decide to do that later. <2> "pull" has not made merge commit, so "git reset --hard" which is a synonym for "git reset --hard HEAD" clears the mess from the index file and the working tree. -<3> merge a topic branch into the current branch, which resulted +<3> Merge a topic branch into the current branch, which resulted in a fast forward. -<4> but you decided that the topic branch is not ready for public +<4> But you decided that the topic branch is not ready for public consumption yet. "pull" or "merge" always leaves the original tip of the current branch in ORIG_HEAD, so resetting hard to it brings your index file and the working tree back to that state, diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 08e7573b9e..1c1978140f 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -27,7 +27,8 @@ SYNOPSIS [ \--cherry-pick ] [ \--encoding[=<encoding>] ] [ \--(author|committer|grep)=<pattern> ] - [ \--regexp-ignore-case ] [ \--extended-regexp ] + [ \--regexp-ignore-case | \-i ] + [ \--extended-regexp | \-E ] [ \--date={local|relative|default|iso|rfc|short} ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] @@ -36,6 +37,7 @@ SYNOPSIS [ \--merge ] [ \--reverse ] [ \--walk-reflogs ] + [ \--no-walk ] [ \--do-walk ] <commit>... [ \-- <paths>... ] DESCRIPTION @@ -227,11 +229,11 @@ limiting may be applied. Limit the commits output to ones with log message that matches the specified pattern (regular expression). ---regexp-ignore-case:: +-i, --regexp-ignore-case:: Match the regexp limiting patterns without regard to letters case. ---extended-regexp:: +-E, --extended-regexp:: Consider the limiting patterns to be extended regular expressions instead of the default basic regular expressions. @@ -397,6 +399,14 @@ These options are mostly targeted for packing of git repositories. Only useful with '--objects'; print the object IDs that are not in packs. +--no-walk:: + + Only show the given revs, but do not traverse their ancestors. + +--do-walk:: + + Overrides a previous --no-walk. + include::pretty-formats.txt[] diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index eea9c9cfe9..4b4d229e60 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -224,7 +224,7 @@ left-to-right. G H I J \ / \ / D E F - \ | / \ + \ | / \ \ | / | \|/ | B C diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 17121ade56..05f40cff6c 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -29,8 +29,8 @@ you create one. The latest stash you created is stored in `$GIT_DIR/refs/stash`; older stashes are found in the reflog of this reference and can be named using -the usual reflog syntax (e.g. `stash@\{1}` is the most recently -created stash, `stash@\{2}` is the one before it, `stash@\{2.hours.ago}` +the usual reflog syntax (e.g. `stash@\{0}` is the most recently +created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}` is also possible). OPTIONS @@ -45,7 +45,7 @@ save:: list:: List the stashes that you currently have. Each 'stash' is listed - with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1} is + with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is the one before, etc.), the name of the branch that was current when the stash was made, and a short description of the commit the stash was based on. @@ -61,7 +61,7 @@ show [<stash>]:: stashed state and its original parent. When no `<stash>` is given, shows the latest one. By default, the command shows the diffstat, but it will accept any format known to `git-diff` (e.g., `git-stash show - -p stash@\{2}` to view the second most recent stash in patch form). + -p stash@\{1}` to view the second most recent stash in patch form). apply [<stash>]:: diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 6f16eb0328..8fd0fc6236 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -27,6 +27,13 @@ The command takes the same set of options as `git-commit`; it shows what would be committed if the same options are given to `git-commit`. +If any paths have been touched in the working tree (that is, +their modification times have changed) but their contents and +permissions are identical to those in the index file, the command +updates the index file. Running `git-status` can thus speed up +subsequent operations such as `git-diff` if the working tree +contains many paths that have been touched but not modified. + OUTPUT ------ diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 0a210e4bea..816340b944 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -435,6 +435,26 @@ Tracking and contributing to an entire Subversion-managed project # of dcommit/rebase/show-ignore should be the same as above. ------------------------------------------------------------------------ +The initial 'git-svn clone' can be quite time-consuming +(especially for large Subversion repositories). If multiple +people (or one person with multiple machines) want to use +git-svn to interact with the same Subversion repository, you can +do the initial 'git-svn clone' to a repository on a server and +have each person clone that repository with 'git clone': + +------------------------------------------------------------------------ +# Do the initial import on a server + ssh server "cd /pub && git-svn clone http://svn.foo.org/project +# Clone locally + git clone server:/pub/project +# Tell git-svn which branch contains the Subversion commits + git update-ref refs/remotes/git-svn origin/master +# Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server) + git-svn init http://svn.foo.org/project +# Pull the latest changes from Subversion + git-svn rebase +------------------------------------------------------------------------ + REBASE VS. PULL/MERGE --------------------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 4c4d1746e0..18f8b6a0a1 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -421,6 +421,22 @@ other to an empty string or to the value "cat", git will not launch a pager. +'GIT_SSH':: + If this environment variable is set then gitlink:git-fetch[1] + and gitlink:git-push[1] will use this command instead + of `ssh` when they need to connect to a remote system. + The 'GIT_SSH' command will be given exactly two arguments: + the 'username@host' (or just 'host') from the URL and the + shell command to execute on that remote system. ++ +To pass options to the program that you want to list in GIT_SSH +you will need to wrap the program and options into a shell script, +then set GIT_SSH to refer to the shell script. ++ +Usually it is easier to configure any desired options through your +personal `.ssh/config` file. Please consult your ssh documentation +for further details. + 'GIT_FLUSH':: If this environment variable is set to "1", then commands such as git-blame (in incremental mode), git-rev-list, git-log, diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 810df07217..8b90a5b980 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -405,7 +405,7 @@ the attributes given to path `t/abc` are computed as follows: and `bar` attributes should be given to this path, so it leaves `foo` and `bar` unset. Attribute `baz` is set. -3. Finally it examines `$GIT_DIR/info/gitattributes`. This file +3. Finally it examines `$GIT_DIR/info/attributes`. This file is used to override the in-tree settings. The first line is a match, and `foo` is set, `bar` is reverted to unspecified state, and `baz` is unset. diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index ea79d74b88..9c83095693 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -18,21 +18,26 @@ pattern. When deciding whether to ignore a path, git normally checks `gitignore` patterns from multiple sources, with the following -order of precedence: +order of precedence, from highest to lowest (within one level of +precedence, the last matching pattern decides the outcome): - * Patterns read from the file specified by the configuration - variable 'core.excludesfile'. - - * Patterns read from `$GIT_DIR/info/exclude`. + * Patterns read from the command line for those commands that support + them. * Patterns read from a `.gitignore` file in the same directory - as the path, or in any parent directory, ordered from the - deepest such file to a file in the root of the repository. + as the path, or in any parent directory, with patterns in the + higher level files (up to the root) being overriden by those in + lower level files down to the directory containing the file. These patterns match relative to the location of the `.gitignore` file. A project normally includes such `.gitignore` files in its repository, containing patterns for files generated as part of the project build. + * Patterns read from `$GIT_DIR/info/exclude`. + + * Patterns read from the file specified by the configuration + variable 'core.excludesfile'. + The underlying git plumbing tools, such as gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read `gitignore` patterns specified by command-line options, or from @@ -49,7 +54,8 @@ Patterns have the following format: - An optional prefix '!' which negates the pattern; any matching file excluded by a previous pattern will become - included again. + included again. If a negated pattern matches, this will + override lower precedence patterns sources. - If the pattern does not contain a slash '/', git treats it as a shell glob pattern and checks for a match against the diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh index e6601bdd82..5433cf8ced 100755 --- a/Documentation/install-doc-quick.sh +++ b/Documentation/install-doc-quick.sh @@ -7,7 +7,7 @@ mandir="$2" SUBDIRECTORY_OK=t USAGE='<refname> <target directory>' . git-sh-setup -export GIT_DIR +cd_to_toplevel test -z "$mandir" && usage if ! git rev-parse --verify "$head^0" >/dev/null; then @@ -18,14 +18,14 @@ fi GIT_INDEX_FILE=`pwd`/.quick-doc.index export GIT_INDEX_FILE rm -f "$GIT_INDEX_FILE" +trap 'rm -f "$GIT_INDEX_FILE"' 0 + git read-tree $head git checkout-index -a -f --prefix="$mandir"/ if test -n "$GZ"; then - cd "$mandir" - for i in `git ls-tree -r --name-only $head` - do - gzip < $i > $i.gz && rm $i - done + git ls-tree -r --name-only $head | + xargs printf "$mandir/%s\n" | + xargs gzip -f fi rm -f "$GIT_INDEX_FILE" diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 746bc5b7f9..973d8dd733 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -1,9 +1,9 @@ --pretty[='<format>']:: - Pretty print the contents of the commit logs in a given format, + Pretty-print the contents of the commit logs in a given format, where '<format>' can be one of 'oneline', 'short', 'medium', 'full', 'fuller', 'email', 'raw' and 'format:<string>'. - When left out the format default to 'medium'. + When omitted, the format defaults to 'medium'. --abbrev-commit:: Instead of showing the full 40-byte hexadecimal commit object diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 781df4174b..b38145faff 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -15,11 +15,11 @@ to name the remote repository: - ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git =============================================================== -SSH is the default transport protocol. You can optionally specify -which user to log-in as, and an alternate, scp-like syntax is also -supported. Both syntaxes support username expansion, -as does the native git protocol. The following three are -identical to the last three above, respectively: +SSH is the default transport protocol over the network. You can +optionally specify which user to log-in as, and an alternate, +scp-like syntax is also supported. Both syntaxes support +username expansion, as does the native git protocol. The following +three are identical to the last three above, respectively: =============================================================== - {startsb}user@{endsb}host.xz:/path/to/repo.git/ @@ -27,8 +27,12 @@ identical to the last three above, respectively: - {startsb}user@{endsb}host.xz:path/to/repo.git =============================================================== -To sync with a local directory, use: +To sync with a local directory, you can use: =============================================================== - /path/to/repo.git/ +- file:///path/to/repo.git/ =============================================================== + +They are mostly equivalent, except when cloning. See +gitlink:git-clone[1] for details. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 14825c6411..f89952ad84 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1,4 +1,4 @@ -Git User's Manual (for version 1.5.1 or newer) +Git User's Manual (for version 1.5.3 or newer) ______________________________________________ @@ -449,7 +449,7 @@ Exploring git history Git is best thought of as a tool for storing the history of a collection of files. It does this by storing compressed snapshots of -the contents of a file heirarchy, together with "commits" which show +the contents of a file hierarchy, together with "commits" which show the relationships between these snapshots. Git provides extremely flexible and fast tools for exploring the @@ -1070,7 +1070,7 @@ about to commit: ------------------------------------------------- $ git diff --cached # difference between HEAD and the index; what - # would be commited if you ran "commit" now. + # would be committed if you ran "commit" now. $ git diff # difference between the index file and your # working directory; changes that would not # be included if you ran "commit" now. @@ -1079,6 +1079,11 @@ $ git diff HEAD # difference between HEAD and working tree; what $ git status # a brief per-file summary of the above. ------------------------------------------------- +You can also use gitlink:git-gui[1] to create commits, view changes in +the index and the working tree files, and individually select diff hunks +for inclusion in the index (by right-clicking on the diff hunk and +choosing "Stage Hunk For Commit"). + [[creating-good-commit-messages]] Creating good commit messages ----------------------------- @@ -1257,7 +1262,7 @@ index 802992c,2b60207..0000000 ++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt ------------------------------------------------- -Recall that the commit which will be commited after we resolve this +Recall that the commit which will be committed after we resolve this conflict will have two parents instead of the usual one: one parent will be HEAD, the tip of the current branch; the other will be the tip of the other branch, which is stored temporarily in MERGE_HEAD. @@ -1351,7 +1356,7 @@ away, you can always return to the pre-merge state with $ git reset --hard HEAD ------------------------------------------------- -Or, if you've already commited the merge that you want to throw away, +Or, if you've already committed the merge that you want to throw away, ------------------------------------------------- $ git reset --hard ORIG_HEAD @@ -1484,6 +1489,38 @@ $ git show HEAD^:path/to/file which will display the given version of the file. +[[interrupted-work]] +Temporarily setting aside work in progress +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While you are in the middle of working on something complicated, you +find an unrelated but obvious and trivial bug. You would like to fix it +before continuing. You can use gitlink:git-stash[1] to save the current +state of your work, and after fixing the bug (or, optionally after doing +so on a different branch and then coming back), unstash the +work-in-progress changes. + +------------------------------------------------ +$ git stash "work in progress for foo feature" +------------------------------------------------ + +This command will save your changes away to the `stash`, and +reset your working tree and the index to match the tip of your +current branch. Then you can make your fix as usual. + +------------------------------------------------ +... edit and test ... +$ git commit -a -m "blorpl: typofix" +------------------------------------------------ + +After that, you can go back to what you were working on with +`git stash apply`: + +------------------------------------------------ +$ git stash apply +------------------------------------------------ + + [[ensuring-good-performance]] Ensuring good performance ------------------------- @@ -1667,24 +1704,19 @@ one step: $ git pull origin master ------------------------------------------------- -In fact, "origin" is normally the default repository to pull from, -and the default branch is normally the HEAD of the remote repository, -so often you can accomplish the above with just +In fact, if you have "master" checked out, then by default "git pull" +merges from the HEAD branch of the origin repository. So often you can +accomplish the above with just a simple ------------------------------------------------- $ git pull ------------------------------------------------- -See the descriptions of the branch.<name>.remote and branch.<name>.merge -options in gitlink:git-config[1] to learn how to control these defaults -depending on the current branch. Also note that the --track option to -gitlink:git-branch[1] and gitlink:git-checkout[1] can be used to -automatically set the default remote branch to pull from at the time -that a branch is created: - -------------------------------------------------- -$ git checkout --track -b maint origin/maint -------------------------------------------------- +More generally, a branch that is created from a remote branch will pull +by default from that branch. See the descriptions of the +branch.<name>.remote and branch.<name>.merge options in +gitlink:git-config[1], and the discussion of the --track option in +gitlink:git-checkout[1], to learn how to control these defaults. In addition to saving you keystrokes, "git pull" also helps you by producing a default commit message documenting the branch and @@ -2479,8 +2511,10 @@ $ gitk origin..mywork & And browse through the list of patches in the mywork branch using gitk, applying them (possibly in a different order) to mywork-new using -cherry-pick, and possibly modifying them as you go using commit ---amend. +cherry-pick, and possibly modifying them as you go using commit --amend. +The git-gui[1] command may also help as it allows you to individually +select diff hunks for inclusion in the index (by right-clicking on the +diff hunk and choosing "Stage Hunk for Commit"). Another technique is to use git-format-patch to create a series of patches, then reset the state to before the patches: |