diff options
Diffstat (limited to 'Documentation')
160 files changed, 2921 insertions, 1307 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 4edf788c3a..fbefe9a45b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -2,7 +2,7 @@ MAN1_TXT= \ $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) \ gitk.txt -MAN5_TXT=gitattributes.txt gitignore.txt +MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt MAN7_TXT=git.txt DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)) @@ -29,7 +29,7 @@ DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) prefix?=$(HOME) bindir?=$(prefix)/bin -mandir?=$(prefix)/man +mandir?=$(prefix)/share/man man1dir=$(mandir)/man1 man5dir=$(mandir)/man5 man7dir=$(mandir)/man7 @@ -41,8 +41,14 @@ ifdef ASCIIDOC8 ASCIIDOC_EXTRA += -a asciidoc7compatible endif 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 @@ -66,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) @@ -74,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 @@ -84,7 +100,7 @@ install: man # Determine "include::" file references in asciidoc files. # doc.dep : $(wildcard *.txt) build-docdep.perl - rm -f $@+ $@ + $(RM) $@+ $@ perl ./build-docdep.perl >$@+ mv $@+ $@ @@ -103,26 +119,28 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ $(cmds_txt): cmd-list.made cmd-list.made: cmd-list.perl $(MAN1_TXT) + $(RM) $@ perl ./cmd-list.perl date >$@ git.7 git.html: git.txt core-intro.txt clean: - rm -f *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 howto-index.txt howto/*.html doc.dep - rm -f $(cmds_txt) *.made + $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.texi *.texi+ howto-index.txt howto/*.html doc.dep + $(RM) $(cmds_txt) *.made %.html : %.txt - rm -f $@+ $@ + $(RM) $@+ $@ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< mv $@+ $@ %.1 %.5 %.7 : %.xml + $(RM) $@ xmlto -m callouts.xsl man $< %.xml : %.txt - rm -f $@+ $@ + $(RM) $@+ $@ $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< mv $@+ $@ @@ -130,14 +148,21 @@ 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 -f $@+ $@ + $(RM) $@+ $@ sh ./howto-index.sh $(wildcard howto/*.txt) >$@+ mv $@+ $@ @@ -147,7 +172,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt WEBDOC_DEST = /pub/software/scm/git/docs $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt - rm -f $@+ $@ + $(RM) $@+ $@ sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+ mv $@+ $@ diff --git a/Documentation/RelNotes-1.5.0.4.txt b/Documentation/RelNotes-1.5.0.4.txt index b727a8d1e5..feefa5dfd4 100644 --- a/Documentation/RelNotes-1.5.0.4.txt +++ b/Documentation/RelNotes-1.5.0.4.txt @@ -20,5 +20,3 @@ Fixes since v1.5.0.3 * Documentation updates * User manual updates - - diff --git a/Documentation/RelNotes-1.5.0.5.txt b/Documentation/RelNotes-1.5.0.5.txt index aa86149d4f..eeec3d73d0 100644 --- a/Documentation/RelNotes-1.5.0.5.txt +++ b/Documentation/RelNotes-1.5.0.5.txt @@ -24,5 +24,3 @@ Fixes since v1.5.0.3 * Documentation updates * User manual updates - - diff --git a/Documentation/RelNotes-1.5.0.6.txt b/Documentation/RelNotes-1.5.0.6.txt index e15447ffdb..c02015ad5f 100644 --- a/Documentation/RelNotes-1.5.0.6.txt +++ b/Documentation/RelNotes-1.5.0.6.txt @@ -19,4 +19,3 @@ Fixes since v1.5.0.5 - user-manual has better cross references. - gitweb installation/deployment procedure is now documented. - diff --git a/Documentation/RelNotes-1.5.1.3.txt b/Documentation/RelNotes-1.5.1.3.txt index 2ddeabd029..876408b65a 100644 --- a/Documentation/RelNotes-1.5.1.3.txt +++ b/Documentation/RelNotes-1.5.1.3.txt @@ -43,4 +43,3 @@ Fixes since v1.5.1.2 description was given by the caller. Also contains various documentation updates. - diff --git a/Documentation/RelNotes-1.5.3.txt b/Documentation/RelNotes-1.5.3.txt new file mode 100644 index 0000000000..e529e11cb2 --- /dev/null +++ b/Documentation/RelNotes-1.5.3.txt @@ -0,0 +1,325 @@ +GIT v1.5.3 Release Notes +======================== + +Updates since v1.5.2 +-------------------- + +* The commit walkers other than http are officially deprecated, + but still supported for now. + +* The submodule support has Porcelain layer. + + Note that the current submodule support is minimal and this is + deliberately so. A design decision we made is that operations + at the supermodule level do not recurse into submodules by + default. The expectation is that later we would add a + mechanism to tell git which submodules the user is interested + in, and this information might be used to determine the + recursive behaviour of certain commands (e.g. "git checkout" + and "git diff"), but currently we haven't agreed on what that + mechanism should look like. Therefore, if you use submodules, + you would probably need "git submodule update" on the + submodules you care about after running a "git checkout" at + the supermodule level. + +* There are a handful pack-objects changes to help you cope better + with repositories with pathologically large blobs in them. + +* For people who need to import from Perforce, a front-end for + fast-import is in contrib/fast-import/. + +* Comes with git-gui 0.8.1. + +* Comes with updated gitk. + +* New commands and options. + + - "git log --date=<format>" can use more formats: iso8601, rfc2822. + + - The hunk header output from "git diff" family can be customized + with the attributes mechanism. See gitattributes(5) for details. + + - "git stash" allows you to quickly save away your work in + progress and replay it later on an updated state. + + - "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. 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 + 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. + + - In addition to core.compression configuration option, + core.loosecompression and pack.compression options can + independently tweak zlib compression levels used for loose + and packed objects. + + - "git ls-tree -l" shows size of blobs pointed at by the + tree entries, similar to "/bin/ls -l". + + - "git rev-list" learned --regexp-ignore-case and + --extended-regexp options to tweak its matching logic used + for --grep fitering. + + - "git describe --contains" is a handier way to call more + obscure command "git name-rev --tags". + + - "git gc --aggressive" tells the command to spend more cycles + to optimize the repository harder. + + - "git repack" learned a "window-memory" limit which + dynamically reduces the window size to stay within the + specified memory usage. + + - "git repack" can be told to split resulting packs to avoid + exceeding limit specified with "--max-pack-size". + + - "git fsck" gained --verbose option. This is really really + verbose but it might help you identify exact commit that is + corrupt in your repository. + + - "git format-patch" learned --numbered-files option. This + may be useful for MH users. + + - "git format-patch" learned format.subjectprefix configuration + variable, which serves the same purpose as "--subject-prefix" + option. + + - "git tag -n -l" shows tag annotations while listing tags. + + - "git cvsimport" can optionally use the separate-remote layout. + + - "git blame" can be told to see through commits that change + whitespaces and indentation levels with "-w" option. + + - "git send-email" can be told not to thread the messages when + sending out more than one patches. + + - "git config" learned NUL terminated output format via -z to + help scripts. + + - "git add" learned "--refresh <paths>..." option to selectively refresh + the cached stat information. + + - "git init -q" makes the command quieter. + + - "git -p command" now has a cousin of opposite sex, "git --no-pager + command". + +* 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 clone" uses -l (hardlink files under .git) by default when + cloning locally. + + - "git bundle create" can now create a bundle without negative refs, + i.e. "everything since the beginning up to certain points". + + - "git diff" (but not the plumbing level "git diff-tree") now + recursively descends into trees by default. + + - "git diff" does not show differences that come only from + stat-dirtiness in the form of "diff --git" header anymore. When + generating a textual diff, it shows a warning message at the end. + + - 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 log" learned --log-size to show the number of bytes in + the log message part of the output to help qgit. + + - "git svn dcommit" retains local merge information. + + - "git svnimport" allows an empty string to be specified as the + trunk/ directory. This is necessary to suck data from a SVN + repository that doe not have trunk/ branches/ and tags/ organization + at all. + + - "git config" to set values also honors type flags like --bool + and --int. + + - core.quotepath configuration can be used to make textual git + output to emit most of the characters in the path literally. + + - "git mergetool" chooses its backend more wisely, taking + notice of its environment such as use of X, Gnome/KDE, etc. + + - "gitweb" shows merge commits a lot nicer than before. The + default view uses more compact --cc format, while the UI + allows to choose normal diff with any parent. + + - snapshot files "gitweb" creates from a repository at + $path/$project/.git are more useful. We use $project part + in the filename, which we used to discard. + + - "git cvsimport" creates lightweight tags; there is no + interesting information we can record in an annotated tag, + and the handcrafted ones the old code created was not + properly formed anyway. + + - "git push" pretends that you immediately fetched back from + the remote by updating corresponding remote tracking + branches if you have any. + + - 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. + + - "git fetch" over git native protocols with "-v" option shows + connection status, and the IP address of the other end, to + help diagnosing problems. + + - We used to have core.legacyheaders configuration, when + set to false, allowed git to write loose objects in a format + that mimicks the format used by objects stored in packs. It + turns out that this was not so useful. Although we will + continue to read objects written in that format, we do not + honor that configuration anymore and create loose objects in + the legacy/traditional format. + + - "--find-copies-harder" option to diff family can now be + spelled as "-C -C" for brevity. + + - "git mailsplit" (hence "git am") can read from Maildir + formatted mailboxes. + + - "git cvsserver" does not barf upon seeing "cvs login" + request. + + - "pack-objects" honors "delta" attribute set in + .gitattributes. It does not attempt to deltify blobs that + come from paths with delta attribute set to false. + + - "new-workdir" script (in contrib) can now be used with a + bare repository. + + - "git mergetool" learned to use gvimdiff. + + - "gitview" (in contrib) has a better blame interface. + + - "git log" and friends did not handle a commit log message + that is larger than 16kB; they do now. + + - "--pretty=oneline" output format for "git log" and friends + deals with "malformed" commit log messages that have more + than one lines in the first paragraph better. We used to + show the first line, cutting the title at mid-sentence; we + concatenate them into a single line and treat the result as + "oneline". + + - "git p4import" has been demoted to contrib status. For + a superior option, checkout the "git p4" front end to + "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 + without parameter defined with "func()", not "func(void)") + have been eradicated. + + - "git tag" and "git verify-tag" have been rewritten in C. + +* Performance Tweaks + + - "git pack-objects" avoids re-deltification cost by caching + small enough delta results it creates while looking for the + best delta candidates. + + - "git pack-objects" learned a new heuristcs to prefer delta + that is shallower in depth over the smallest delta + possible. This improves both overall packfile access + performance and packfile density. + + - diff-delta code that is used for packing has been improved + to work better on big files. + + - when there are more than one pack files in the repository, + the runtime used to try finding an object always from the + newest packfile; it now tries the same packfile as we found + the object requested the last time, which exploits the + locality of references. + + - verifying pack contents done by "git fsck --full" got boost + by carefully choosing the order to verify objects in them. + + - "git read-tree -m" to read into an already populated index + has been optimized vastly. The effect of this can be seen + when switching branches that have differences in only a + handful paths. + + - "git commit paths..." has also been optimized. + + +Fixes since v1.5.2 +------------------ + +All of the fixes in v1.5.2 maintenance series are included in +this release, unless otherwise noted. + +* Bugfixes + + - "gitweb" had trouble handling non UTF-8 text with older + Encode.pm Perl module. + +-- +exec >/var/tmp/1 +O=v1.5.3-rc6 +echo O=`git describe refs/heads/master` +git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b94d9a8166..01354c2bb5 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -14,6 +14,8 @@ Checklist (and a short version for the impatient): commit message (or just use the option "-s" when committing) to confirm that you agree to the Developer's Certificate of Origin + - make sure that you have tests for the bug you are fixing + - make sure that the test suite passes after your commit Patch: @@ -33,6 +35,8 @@ Checklist (and a short version for the impatient): - if you change, add, or remove a command line option or make some other user interface change, the associated documentation should be updated as well. + - if your name is not writable in ASCII, make sure that + you send off a message in the correct encoding. Long version: @@ -239,7 +243,7 @@ One test you could do yourself if your MUA is set up correctly is: $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply $ git checkout test-apply $ git reset --hard - $ git applymbox a.patch + $ git am a.patch If it does not apply correctly, there can be various reasons. @@ -247,7 +251,7 @@ If it does not apply correctly, there can be various reasons. does not have much to do with your MUA. Please rebase the patch appropriately. -* Your MUA corrupted your patch; applymbox would complain that +* Your MUA corrupted your patch; "am" would complain that the patch does not apply. Look at .dotest/ subdirectory and see what 'patch' file contains and check for the common corruption patterns mentioned above. @@ -292,15 +296,15 @@ diff --git a/pico/pico.c b/pico/pico.c --- a/pico/pico.c +++ b/pico/pico.c @@ -219,7 +219,9 @@ PICO *pm; - switch(pico_all_done){ /* prepare for/handle final events */ - case COMP_EXIT : /* already confirmed */ - packheader(); + switch(pico_all_done){ /* prepare for/handle final events */ + case COMP_EXIT : /* already confirmed */ + packheader(); +#if 0 - stripwhitespace(); + stripwhitespace(); +#endif - c |= COMP_EXIT; - break; - + c |= COMP_EXIT; + break; + (Daniel Barkalow) diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index a0d8459e21..af5b1558a6 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -61,5 +61,3 @@ ifdef::backend-xhtml11[] [gitlink-inlinemacro] <a href="{target}.html">{target}{0?({0})}</a> endif::backend-xhtml11[] - - 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 443802a9a3..4ee76eaf99 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -68,12 +68,12 @@ 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 git-annotate ancillaryinterrogators -git-applymbox ancillaryinterrogators -git-applypatch purehelpers git-apply plumbingmanipulators git-archimport foreignscminterface git-archive mainporcelain @@ -82,16 +82,18 @@ 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 +git-citool mainporcelain 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 @@ -99,13 +101,14 @@ 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 git-fetch-pack synchingrepositories +git-filter-branch ancillarymanipulators git-fmt-merge-msg purehelpers git-for-each-ref plumbinginterrogators git-format-patch mainporcelain @@ -113,6 +116,7 @@ git-fsck ancillaryinterrogators git-gc mainporcelain git-get-tar-commit-id ancillaryinterrogators git-grep mainporcelain +git-gui mainporcelain git-hash-object plumbingmanipulators git-http-fetch synchelpers git-http-push synchelpers @@ -129,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 @@ -156,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 @@ -178,8 +181,10 @@ git-show-ref plumbinginterrogators git-sh-setup purehelpers git-ssh-fetch synchingrepositories git-ssh-upload synchingrepositories +git-stash mainporcelain git-status mainporcelain git-stripspace purehelpers +git-submodule mainporcelain git-svn foreignscminterface git-svnimport foreignscminterface git-symbolic-ref plumbingmanipulators diff --git a/Documentation/config.txt b/Documentation/config.txt index a75f7f7664..903610fecf 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 @@ -117,6 +117,18 @@ core.fileMode:: the working copy are ignored; useful on broken filesystems like FAT. See gitlink:git-update-index[1]. True by default. +core.quotepath:: + The commands that output paths (e.g. `ls-files`, + `diff`), when not given the `-z` option, will quote + "unusual" characters in the pathname by enclosing the + pathname in a double-quote pair and with backslashes the + same way strings in C source code are quoted. If this + variable is set to false, the bytes higher than 0x80 are + not quoted but output as verbatim. Note that double + quote, backslash and control characters are always + quoted without `-z` regardless of the setting of this + variable. + core.autocrlf:: If true, makes git convert `CRLF` at the end of lines in text files to `LF` when reading from the filesystem, and convert in reverse when @@ -172,8 +184,15 @@ repository that ends in "/.git" is assumed to be not bare (bare = false), while all other repositories are assumed to be bare (bare = true). +core.worktree:: + Set the path to the working tree. The value will not be + used in combination with repositories found automatically in + a .git directory (i.e. $GIT_DIR is not set). + This can be overriden by the GIT_WORK_TREE environment + variable and the '--work-tree' command line option. + core.logAllRefUpdates:: - Updates to a ref <ref> is logged to the file + Enable the reflog. Updates to a ref <ref> is logged to the file "$GIT_DIR/logs/<ref>", by appending the new and old SHA1, the date/time and the reason of the update, but only when the file exists. If this configuration @@ -204,23 +223,16 @@ core.warnAmbiguousRefs:: and might match multiple refs in the .git/refs/ tree. True by default. core.compression:: + An integer -1..9, indicating a default compression level. + -1 is the zlib default. 0 means no compression, + and 1..9 are various speed/size tradeoffs, 9 being slowest. + +core.loosecompression:: An integer -1..9, indicating the compression level for objects that - are not in a pack file. -1 is the zlib and git default. 0 means no + are not in a pack file. -1 is the zlib default. 0 means no compression, and 1..9 are various speed/size tradeoffs, 9 being - slowest. - -core.legacyheaders:: - A boolean which - changes the format of loose objects so that they are more - efficient to pack and to send out of the repository over git - native protocol, since v1.4.2. However, loose objects - written in the new format cannot be read by git older than - that version; people fetching from your repository using - older versions of git over dumb transports (e.g. http) - will also be affected. -+ -To let git use the new loose object format, you have to -set core.legacyheaders to false. + slowest. If not set, defaults to core.compression. If that is + not set, defaults to 0 (best speed). core.packedGitWindowSize:: Number of bytes of a pack file to map into memory in a @@ -269,6 +281,18 @@ core.excludesfile:: of files which are not meant to be tracked. See gitlink:gitignore[5]. +core.editor:: + Commands such as `commit` and `tag` that lets you edit + messages by launching 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`, `VISUAL` and + `EDITOR` environment variables and then finally `vi`. + +core.pager:: + The command that git will use to paginate output. Can be overridden + with the `GIT_PAGER` environment variable. + alias.*:: Command aliases for the gitlink:git[1] command wrapper - e.g. after defining "alias.last = cat-file commit HEAD", the invocation @@ -369,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'. @@ -397,6 +424,11 @@ format.suffix:: `.patch`. Use this variable to change that suffix (make sure to include the dot if you want it). +gc.aggressiveWindow:: + The window size parameter used in the delta compression + algorithm used by 'git gc --aggressive'. This defaults + to 10. + gc.packrefs:: `git gc` does not run `git pack-refs` in a bare repository by default so that older dumb-transport clients can still fetch @@ -427,12 +459,17 @@ gc.rerereunresolved:: kept for this many days when `git rerere gc` is run. The default is 15 days. See gitlink:git-rerere[1]. +rerere.enabled:: + Activate recording of resolved conflicts, so that identical + conflict hunks can be resolved automatically, should they + be encountered again. See gitlink:git-rerere[1]. + gitcvs.enabled:: - Whether the cvs server interface is enabled for this repository. + Whether the CVS server interface is enabled for this repository. See gitlink:git-cvsserver[1]. gitcvs.logfile:: - Path to a log file where the cvs server interface well... logs + Path to a log file where the CVS server interface well... logs various stuff. See gitlink:git-cvsserver[1]. gitcvs.allbinary:: @@ -463,10 +500,10 @@ gitcvs.dbuser, gitcvs.dbpass:: 'gitcvs.dbuser' supports variable substitution (see gitlink:git-cvsserver[1] for details). -All gitcvs variables except for 'gitcvs.allbinary' can also specifed -as 'gitcvs.<access_method>.<varname>' (where 'access_method' is one -of "ext" and "pserver") to make them apply only for the given access -method. +All gitcvs variables except for 'gitcvs.allbinary' can also be +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. http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing @@ -533,7 +570,7 @@ merge.summary:: merge.tool:: Controls which merge resolution program is used by gitlink:git-mergetool[l]. Valid values are: "kdiff3", "tkdiff", - "meld", "xxdiff", "emerge", "vimdiff", and "opendiff" + "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", and "opendiff". merge.verbosity:: Controls the amount of output shown by the recursive merge @@ -541,6 +578,7 @@ merge.verbosity:: 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 overriden by 'GIT_MERGE_VERBOSITY' environment variable. merge.<driver>.name:: Defines a human readable name for a custom low-level @@ -563,6 +601,28 @@ pack.depth:: The maximum delta depth used by gitlink:git-pack-objects[1] when no maximum depth is given on the command line. Defaults to 50. +pack.windowMemory:: + The window memory size limit used by gitlink:git-pack-objects[1] + when no limit is given on the command line. The value can be + suffixed with "k", "m", or "g". Defaults to 0, meaning no + limit. + +pack.compression:: + An integer -1..9, indicating the compression level for objects + in a pack file. -1 is the zlib default. 0 means no + compression, and 1..9 are various speed/size tradeoffs, 9 being + slowest. If not set, defaults to core.compression. If that is + not set, defaults to -1. + +pack.deltaCacheSize:: + The maximum memory in bytes used for caching deltas in + gitlink:git-pack-objects[1]. + A value of 0 means no limit. Defaults to 0. + +pack.deltaCacheLimit:: + The maxium size of a delta, that is cached in + gitlink:git-pack-objects[1]. Defaults to 1000. + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. @@ -615,15 +675,11 @@ showbranch.default:: See gitlink:git-show-branch[1]. tar.umask:: - By default, gitlink:git-tar-tree[1] sets file and directories modes - to 0666 or 0777. While this is both useful and acceptable for projects - such as the Linux Kernel, it might be excessive for other projects. - With this variable, it becomes possible to tell - gitlink:git-tar-tree[1] to apply a specific umask to the modes above. - The special value "user" indicates that the user's current umask will - be used. This should be enough for most projects, as it will lead to - the same permissions as gitlink:git-checkout[1] would use. The default - value remains 0, which means world read-write. + This variable can be used to restrict the permission bits of + tar archive entries. The default is 0002, which turns off the + world write bit. The special value "user" indicates that the + archiving user's umask will be used instead. See umask(2) and + gitlink:git-archive[1]. user.email:: Your email address to be recorded in any newly created commits. @@ -668,5 +724,3 @@ receive.denyNonFastForwards:: transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are not set, the value of this variable is used instead. - - diff --git a/Documentation/core-intro.txt b/Documentation/core-intro.txt index eea44d9d56..f3cc2238c7 100644 --- a/Documentation/core-intro.txt +++ b/Documentation/core-intro.txt @@ -528,7 +528,7 @@ paths that have been trivially merged. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sadly, many merges aren't trivial. If there are files that have -been added.moved or removed, or if both branches have modified the +been added, moved or removed, or if both branches have modified the same file, you will be left with an index tree that contains "merge entries" in it. Such an index tree can 'NOT' be written out to a tree object, and you will have to resolve any such merge clashes using diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 6b9b9ad7d1..4fb6f4143c 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -9,11 +9,11 @@ repository, mainly because being hands-on and using explicit examples is often the best way of explaining what is going on. In normal life, most people wouldn't use the "core" git programs -directly, but rather script around them to make them more palatable. +directly, but rather script around them to make them more palatable. Understanding the core git stuff may help some people get those scripts done, though, and it may also be instructive in helping people understand what it is that the higher-level helper scripts are actually -doing. +doing. The core git is often called "plumbing", with the prettier user interfaces on top of it called "porcelain". You may not want to use the @@ -41,7 +41,7 @@ Creating a new git repository couldn't be easier: all git repositories start out empty, and the only thing you need to do is find yourself a subdirectory that you want to use as a working tree - either an empty one for a totally new project, or an existing working tree that you want -to import into git. +to import into git. For our first example, we're going to start a totally new repository from scratch, with no pre-existing files, and we'll call it `git-tutorial`. @@ -169,7 +169,7 @@ $ ls .git/objects/??/* and see two files: ---------------- -.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238 +.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238 .git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962 ---------------- @@ -220,7 +220,7 @@ you have not actually really "checked in" your files into git so far, you've only *told* git about them. However, since git knows about them, you can now start using some of the -most basic git commands to manipulate the files or look at their status. +most basic git commands to manipulate the files or look at their status. In particular, let's not even check in the two files into git yet, we'll start off by adding another line to `hello` first: @@ -350,7 +350,7 @@ Making a change Remember how we did the `git-update-index` on file `hello` and then we changed `hello` afterward, and could compare the new state of `hello` with the -state we saved in the index file? +state we saved in the index file? Further, remember how I said that `git-write-tree` writes the contents of the *index* file to the tree, and thus what we just committed was in @@ -370,7 +370,7 @@ file and the working tree, `git-diff-index` shows the differences between a committed *tree* and either the index file or the working tree. In other words, `git-diff-index` wants a tree to be diffed against, and before we did the commit, we couldn't do that, because we -didn't have anything to diff against. +didn't have anything to diff against. But now we can do @@ -379,7 +379,7 @@ $ git-diff-index -p HEAD ---------------- (where `-p` has the same meaning as it did in `git-diff-files`), and it -will show us the same difference, but for a totally different reason. +will show us the same difference, but for a totally different reason. Now we're comparing the working tree not against the index file, but against the tree we just wrote. It just so happens that those two are obviously the same, so we get the same result. @@ -398,7 +398,7 @@ working tree, but when given the `\--cached` flag, it is told to instead compare against just the index cache contents, and ignore the current working tree state entirely. Since we just wrote the index file to HEAD, doing `git-diff-index \--cached -p HEAD` should thus return -an empty set of differences, and that's exactly what it does. +an empty set of differences, and that's exactly what it does. [NOTE] ================ @@ -549,7 +549,7 @@ $ git-whatchanged -p --root ---------------- and you will see exactly what has changed in the repository over its -short history. +short history. [NOTE] The `\--root` flag is a flag to `git-diff-tree` to tell it to @@ -637,7 +637,7 @@ So the mental model of "the git information is always tied directly to the working tree that it describes" may not be technically 100% accurate, but it's a good model for all normal use. -This has two implications: +This has two implications: - if you grow bored with the tutorial repository you created (or you've made a mistake and want to start all over), you can just do simple @@ -705,7 +705,7 @@ Many (most?) public remote repositories will not contain any of the checked out files or even an index file, and will *only* contain the actual core git files. Such a repository usually doesn't even have the `.git` subdirectory, but has all the git files directly in the -repository. +repository. To create your own local live copy of such a "raw" git repository, you'd first create your own subdirectory for the project, and then copy the @@ -718,7 +718,7 @@ $ cd my-git $ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git ---------------- -followed by +followed by ---------------- $ git-read-tree HEAD @@ -738,7 +738,7 @@ up-to-date (so that you don't have to refresh it afterward), and the `-a` flag means "check out all files" (if you have a stale copy or an older version of a checked out tree you may also need to add the `-f` flag first, to tell git-checkout-index to *force* overwriting of any old -files). +files). Again, this can all be simplified with @@ -751,7 +751,7 @@ $ git checkout which will end up doing all of the above for you. You have now successfully copied somebody else's (mine) remote -repository, and checked it out. +repository, and checked it out. Creating a new branch @@ -760,14 +760,14 @@ Creating a new branch Branches in git are really nothing more than pointers into the git object database from within the `.git/refs/` subdirectory, and as we already discussed, the `HEAD` branch is nothing but a symlink to one of -these object pointers. +these object pointers. You can at any time create a new branch by just picking an arbitrary point in the project history, and just writing the SHA1 name of that object into a file under `.git/refs/heads/`. You can use any filename you want (and indeed, subdirectories), but the convention is that the "normal" branch is called `master`. That's just a convention, though, -and nothing enforces it. +and nothing enforces it. To show that as an example, let's go back to the git-tutorial repository we used earlier, and create a branch in it. You do that by simply just @@ -778,7 +778,7 @@ $ git checkout -b mybranch ------------ will create a new branch based at the current `HEAD` position, and switch -to it. +to it. [NOTE] ================================================ @@ -825,7 +825,7 @@ checking it out and switching to it. If so, just use the command $ git branch <branchname> [startingpoint] ------------ -which will simply _create_ the branch, but will not do anything further. +which will simply _create_ the branch, but will not do anything further. You can then later -- once you decide that you want to actually develop on that branch -- switch to that branch with a regular `git checkout` with the branchname as the argument. @@ -884,7 +884,7 @@ $ gitk --all will show you graphically both of your branches (that's what the `\--all` means: normally it will just show you your current `HEAD`) and their histories. You can also see exactly how they came to be from a common -source. +source. Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want to merge the work we did on the `mybranch` branch into the `master` @@ -905,8 +905,8 @@ of it as it can automatically (which in this case is just merge the `example` file, which had no differences in the `mybranch` branch), and say: ---------------- - Auto-merging hello - CONFLICT (content): Merge conflict in hello + Auto-merging hello + CONFLICT (content): Merge conflict in hello Automatic merge failed; fix up by hand ---------------- @@ -1387,7 +1387,7 @@ repository. Kernel.org mirror network takes care of the propagation to other publicly visible machines: ------------ -$ git push master.kernel.org:/pub/scm/git/git.git/ +$ git push master.kernel.org:/pub/scm/git/git.git/ ------------ diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index e38a1f1405..001503205b 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -1,7 +1,7 @@ The output format from "git-diff-index", "git-diff-tree" and "git-diff-files" are very similar. -These commands all compare two sets of things; what is +These commands all compare two sets of things; what is compared differs: git-diff-index <tree-ish>:: @@ -126,6 +126,13 @@ the file that rename/copy produces, respectively. If there is need for such substitution then the whole pathname is put in double quotes. +The similarity index is the percentage of unchanged lines, and +the dissimilarity index is the percentage of changed lines. It +is a rounded down integer, followed by a percent sign. The +similarity index value of 100% is thus reserved for two equal +files, while 100% dissimilarity means that no line from the old +file made it into the new one. + combined diff format -------------------- @@ -139,28 +146,28 @@ index fabadb8,cc95eb0..4866510 --- a/describe.c +++ b/describe.c @@@ -98,20 -98,12 +98,20 @@@ - return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1; + return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1; } - + - static void describe(char *arg) -static void describe(struct commit *cmit, int last_one) ++static void describe(char *arg, int last_one) { + unsigned char sha1[20]; + struct commit *cmit; - struct commit_list *list; - static int initialized = 0; - struct commit_name *n; - + struct commit_list *list; + static int initialized = 0; + struct commit_name *n; + + if (get_sha1(arg, sha1) < 0) + usage(describe_usage); + cmit = lookup_commit_reference(sha1); + if (!cmit) + usage(describe_usage); + - if (!initialized) { - initialized = 1; - for_each_ref(get_name); + if (!initialized) { + initialized = 1; + for_each_ref(get_name); ------------ 1. It is preceded with a "git diff" header, that looks like @@ -233,4 +240,3 @@ parents). When shown by `git diff-files -c`, it compares the two unresolved merge parents with the working tree file (i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka "their version"). - diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 1689c74817..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. @@ -86,7 +95,7 @@ Detect renames. -C:: - Detect copies as well as renames. + Detect copies as well as renames. See also `--find-copies-harder`. --diff-filter=[ACDMRTUXB*]:: Select only files that are Added (`A`), Copied (`C`), @@ -100,12 +109,13 @@ that matches other criteria, nothing is selected. --find-copies-harder:: - For performance reasons, by default, -C option finds copies only - if the original file of the copy was modified in the same + For performance reasons, by default, `-C` option finds copies only + if the original file of the copy was modified in the same changeset. This flag makes the command inspect unmodified files as candidates for the source of copy. This is a very expensive operation for large - projects, so use it with caution. + projects, so use it with caution. Giving more than one + `-C` option has the same effect. -l<num>:: -M and -C options require O(n^2) processing time where n @@ -167,5 +177,13 @@ --quiet:: Disable all output of the program. Implies --exit-code. +--ext-diff:: + Allow an external diff helper to be executed. If you set an + external diff driver with gitlink:gitattributes(5), you need + to use this option with gitlink:git-log(1) and friends. + +--no-ext-diff:: + Disallow external diff drivers. + For more detailed explanation on these common options, see also link:diffcore.html[diffcore documentation]. diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt index 34cd306bb1..c6a983a5d5 100644 --- a/Documentation/diffcore.txt +++ b/Documentation/diffcore.txt @@ -71,7 +71,7 @@ The first transformation in the chain is diffcore-pathspec, and is controlled by giving the pathname parameters to the git-diff-* commands on the command line. The pathspec is used to limit the world diff operates in. It removes the filepairs -outside the specified set of pathnames. E.g. If the input set +outside the specified set of pathnames. E.g. If the input set of filepairs included: ------------------------------------------------ @@ -269,4 +269,3 @@ Documentation *.c t ------------------------------------------------ - diff --git a/Documentation/docbook-xsl.css b/Documentation/docbook-xsl.css index 8821e305dd..b878b385c6 100644 --- a/Documentation/docbook-xsl.css +++ b/Documentation/docbook-xsl.css @@ -1,286 +1,286 @@ -/*
- CSS stylesheet for XHTML produced by DocBook XSL stylesheets.
- Tested with XSL stylesheets 1.61.2, 1.67.2
-*/
-
-span.strong {
- font-weight: bold;
-}
-
-body blockquote {
- margin-top: .75em;
- line-height: 1.5;
- margin-bottom: .75em;
-}
-
-html body {
- margin: 1em 5% 1em 5%;
- line-height: 1.2;
-}
-
-body div {
- margin: 0;
-}
-
-h1, h2, h3, h4, h5, h6,
-div.toc p b,
-div.list-of-figures p b,
-div.list-of-tables p b,
-div.abstract p.title
-{
- color: #527bbd;
- font-family: tahoma, verdana, sans-serif;
-}
-
-div.toc p:first-child,
-div.list-of-figures p:first-child,
-div.list-of-tables p:first-child,
-div.example p.title
-{
- margin-bottom: 0.2em;
-}
-
-body h1 {
- margin: .0em 0 0 -4%;
- line-height: 1.3;
- border-bottom: 2px solid silver;
-}
-
-body h2 {
- margin: 0.5em 0 0 -4%;
- line-height: 1.3;
- border-bottom: 2px solid silver;
-}
-
-body h3 {
- margin: .8em 0 0 -3%;
- line-height: 1.3;
-}
-
-body h4 {
- margin: .8em 0 0 -3%;
- line-height: 1.3;
-}
-
-body h5 {
- margin: .8em 0 0 -2%;
- line-height: 1.3;
-}
-
-body h6 {
- margin: .8em 0 0 -1%;
- line-height: 1.3;
-}
-
-body hr {
- border: none; /* Broken on IE6 */
-}
-div.footnotes hr {
- border: 1px solid silver;
-}
-
-div.navheader th, div.navheader td, div.navfooter td {
- font-family: sans-serif;
- font-size: 0.9em;
- font-weight: bold;
- color: #527bbd;
-}
-div.navheader img, div.navfooter img {
- border-style: none;
-}
-div.navheader a, div.navfooter a {
- font-weight: normal;
-}
-div.navfooter hr {
- border: 1px solid silver;
-}
-
-body td {
- line-height: 1.2
-}
-
-body th {
- line-height: 1.2;
-}
-
-ol {
- line-height: 1.2;
-}
-
-ul, body dir, body menu {
- line-height: 1.2;
-}
-
-html {
- margin: 0;
- padding: 0;
-}
-
-body h1, body h2, body h3, body h4, body h5, body h6 {
- margin-left: 0
-}
-
-body pre {
- margin: 0.5em 10% 0.5em 1em;
- line-height: 1.0;
- color: navy;
-}
-
-tt.literal, code.literal {
- color: navy;
-}
-
-div.literallayout p {
- padding: 0em;
- margin: 0em;
-}
-
-div.literallayout {
- font-family: monospace;
-# margin: 0.5em 10% 0.5em 1em;
- margin: 0em;
- color: navy;
- border: 1px solid silver;
- background: #f4f4f4;
- padding: 0.5em;
-}
-
-.programlisting, .screen {
- border: 1px solid silver;
- background: #f4f4f4;
- margin: 0.5em 10% 0.5em 0;
- padding: 0.5em 1em;
-}
-
-div.sidebar {
- background: #ffffee;
- margin: 1.0em 10% 0.5em 0;
- padding: 0.5em 1em;
- border: 1px solid silver;
-}
-div.sidebar * { padding: 0; }
-div.sidebar div { margin: 0; }
-div.sidebar p.title {
- font-family: sans-serif;
- margin-top: 0.5em;
- margin-bottom: 0.2em;
-}
-
-div.bibliomixed {
- margin: 0.5em 5% 0.5em 1em;
-}
-
-div.glossary dt {
- font-weight: bold;
-}
-div.glossary dd p {
- margin-top: 0.2em;
-}
-
-dl {
- margin: .8em 0;
- line-height: 1.2;
-}
-
-dt {
- margin-top: 0.5em;
-}
-
-dt span.term {
- font-style: italic;
-}
-
-div.variablelist dd p {
- margin-top: 0;
-}
-
-div.itemizedlist li, div.orderedlist li {
- margin-left: -0.8em;
- margin-top: 0.5em;
-}
-
-ul, ol {
- list-style-position: outside;
-}
-
-div.sidebar ul, div.sidebar ol {
- margin-left: 2.8em;
-}
-
-div.itemizedlist p.title,
-div.orderedlist p.title,
-div.variablelist p.title
-{
- margin-bottom: -0.8em;
-}
-
-div.revhistory table {
- border-collapse: collapse;
- border: none;
-}
-div.revhistory th {
- border: none;
- color: #527bbd;
- font-family: tahoma, verdana, sans-serif;
-}
-div.revhistory td {
- border: 1px solid silver;
-}
-
-/* Keep TOC and index lines close together. */
-div.toc dl, div.toc dt,
-div.list-of-figures dl, div.list-of-figures dt,
-div.list-of-tables dl, div.list-of-tables dt,
-div.indexdiv dl, div.indexdiv dt
-{
- line-height: normal;
- margin-top: 0;
- margin-bottom: 0;
-}
-
-/*
- Table styling does not work because of overriding attributes in
- generated HTML.
-*/
-div.table table,
-div.informaltable table
-{
- margin-left: 0;
- margin-right: 5%;
- margin-bottom: 0.8em;
-}
-div.informaltable table
-{
- margin-top: 0.4em
-}
-div.table thead,
-div.table tfoot,
-div.table tbody,
-div.informaltable thead,
-div.informaltable tfoot,
-div.informaltable tbody
-{
- /* No effect in IE6. */
- border-top: 2px solid #527bbd;
- border-bottom: 2px solid #527bbd;
-}
-div.table thead, div.table tfoot,
-div.informaltable thead, div.informaltable tfoot
-{
- font-weight: bold;
-}
-
-div.mediaobject img {
- border: 1px solid silver;
- margin-bottom: 0.8em;
-}
-div.figure p.title,
-div.table p.title
-{
- margin-top: 1em;
- margin-bottom: 0.4em;
-}
-
-@media print {
- div.navheader, div.navfooter { display: none; }
-}
+/* + CSS stylesheet for XHTML produced by DocBook XSL stylesheets. + Tested with XSL stylesheets 1.61.2, 1.67.2 +*/ + +span.strong { + font-weight: bold; +} + +body blockquote { + margin-top: .75em; + line-height: 1.5; + margin-bottom: .75em; +} + +html body { + margin: 1em 5% 1em 5%; + line-height: 1.2; +} + +body div { + margin: 0; +} + +h1, h2, h3, h4, h5, h6, +div.toc p b, +div.list-of-figures p b, +div.list-of-tables p b, +div.abstract p.title +{ + color: #527bbd; + font-family: tahoma, verdana, sans-serif; +} + +div.toc p:first-child, +div.list-of-figures p:first-child, +div.list-of-tables p:first-child, +div.example p.title +{ + margin-bottom: 0.2em; +} + +body h1 { + margin: .0em 0 0 -4%; + line-height: 1.3; + border-bottom: 2px solid silver; +} + +body h2 { + margin: 0.5em 0 0 -4%; + line-height: 1.3; + border-bottom: 2px solid silver; +} + +body h3 { + margin: .8em 0 0 -3%; + line-height: 1.3; +} + +body h4 { + margin: .8em 0 0 -3%; + line-height: 1.3; +} + +body h5 { + margin: .8em 0 0 -2%; + line-height: 1.3; +} + +body h6 { + margin: .8em 0 0 -1%; + line-height: 1.3; +} + +body hr { + border: none; /* Broken on IE6 */ +} +div.footnotes hr { + border: 1px solid silver; +} + +div.navheader th, div.navheader td, div.navfooter td { + font-family: sans-serif; + font-size: 0.9em; + font-weight: bold; + color: #527bbd; +} +div.navheader img, div.navfooter img { + border-style: none; +} +div.navheader a, div.navfooter a { + font-weight: normal; +} +div.navfooter hr { + border: 1px solid silver; +} + +body td { + line-height: 1.2 +} + +body th { + line-height: 1.2; +} + +ol { + line-height: 1.2; +} + +ul, body dir, body menu { + line-height: 1.2; +} + +html { + margin: 0; + padding: 0; +} + +body h1, body h2, body h3, body h4, body h5, body h6 { + margin-left: 0 +} + +body pre { + margin: 0.5em 10% 0.5em 1em; + line-height: 1.0; + color: navy; +} + +tt.literal, code.literal { + color: navy; +} + +div.literallayout p { + padding: 0em; + margin: 0em; +} + +div.literallayout { + font-family: monospace; +# margin: 0.5em 10% 0.5em 1em; + margin: 0em; + color: navy; + border: 1px solid silver; + background: #f4f4f4; + padding: 0.5em; +} + +.programlisting, .screen { + border: 1px solid silver; + background: #f4f4f4; + margin: 0.5em 10% 0.5em 0; + padding: 0.5em 1em; +} + +div.sidebar { + background: #ffffee; + margin: 1.0em 10% 0.5em 0; + padding: 0.5em 1em; + border: 1px solid silver; +} +div.sidebar * { padding: 0; } +div.sidebar div { margin: 0; } +div.sidebar p.title { + font-family: sans-serif; + margin-top: 0.5em; + margin-bottom: 0.2em; +} + +div.bibliomixed { + margin: 0.5em 5% 0.5em 1em; +} + +div.glossary dt { + font-weight: bold; +} +div.glossary dd p { + margin-top: 0.2em; +} + +dl { + margin: .8em 0; + line-height: 1.2; +} + +dt { + margin-top: 0.5em; +} + +dt span.term { + font-style: italic; +} + +div.variablelist dd p { + margin-top: 0; +} + +div.itemizedlist li, div.orderedlist li { + margin-left: -0.8em; + margin-top: 0.5em; +} + +ul, ol { + list-style-position: outside; +} + +div.sidebar ul, div.sidebar ol { + margin-left: 2.8em; +} + +div.itemizedlist p.title, +div.orderedlist p.title, +div.variablelist p.title +{ + margin-bottom: -0.8em; +} + +div.revhistory table { + border-collapse: collapse; + border: none; +} +div.revhistory th { + border: none; + color: #527bbd; + font-family: tahoma, verdana, sans-serif; +} +div.revhistory td { + border: 1px solid silver; +} + +/* Keep TOC and index lines close together. */ +div.toc dl, div.toc dt, +div.list-of-figures dl, div.list-of-figures dt, +div.list-of-tables dl, div.list-of-tables dt, +div.indexdiv dl, div.indexdiv dt +{ + line-height: normal; + margin-top: 0; + margin-bottom: 0; +} + +/* + Table styling does not work because of overriding attributes in + generated HTML. +*/ +div.table table, +div.informaltable table +{ + margin-left: 0; + margin-right: 5%; + margin-bottom: 0.8em; +} +div.informaltable table +{ + margin-top: 0.4em +} +div.table thead, +div.table tfoot, +div.table tbody, +div.informaltable thead, +div.informaltable tfoot, +div.informaltable tbody +{ + /* No effect in IE6. */ + border-top: 2px solid #527bbd; + border-bottom: 2px solid #527bbd; +} +div.table thead, div.table tfoot, +div.informaltable thead, div.informaltable tfoot +{ + font-weight: bold; +} + +div.mediaobject img { + border: 1px solid silver; + margin-bottom: 0.8em; +} +div.figure p.title, +div.table p.title +{ + margin-top: 1em; + margin-bottom: 0.4em; +} + +@media print { + div.navheader, div.navfooter { display: none; } +} 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/fetch-options.txt b/Documentation/fetch-options.txt index bdc7332c7b..da034223f3 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -52,4 +52,3 @@ Deepen the history of a 'shallow' repository created by `git clone` with `--depth=<depth>` option (see gitlink:git-clone[1]) by the specified number of commits. - 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 a0c9f68580..3383aca9af 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -3,32 +3,37 @@ 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 -------- -'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>... +'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--refresh] [--] <file>... 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 'git add' command will not add ignored files by default. If any +ignored files were explicitly specified on the command line, 'git add' +will fail with a list of ignored files. Ignored files reached by +directory recursion or filename globbing will be silently ignored. +The 'add' command can be used to add ignored files with the `-f` +(force) option. Please see gitlink:git-commit[1] for alternative ways to add content to a commit. @@ -63,6 +68,10 @@ OPTIONS command line. If no paths are specified, all tracked files are updated. +\--refresh:: + Don't add the file(s), but only refresh their stat() + information in the index. + \--:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken @@ -228,4 +237,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index ba79773f79..e4a6b3a6f0 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git-am' [--signoff] [--dotest=<dir>] [--keep] [--utf8 | --no-utf8] [--3way] [--interactive] [--binary] [--whitespace=<option>] [-C<n>] [-p<n>] - <mbox>... + <mbox>|<Maildir>... 'git-am' [--skip | --resolved] DESCRIPTION @@ -23,9 +23,10 @@ current branch. OPTIONS ------- -<mbox>...:: +<mbox>|<Maildir>...:: The list of mailbox files to read patches from. If you do not - supply this argument, reads from the standard input. + supply this argument, reads from the standard input. If you supply + directories, they'll be treated as Maildirs. -s, --signoff:: Add `Signed-off-by:` line to the commit message, using @@ -126,8 +127,7 @@ is terminated before the first occurrence of such a line. When initially invoking it, you give it names of the mailboxes to crunch. Upon seeing the first patch that does not apply, it -aborts in the middle, just like 'git-applymbox' does. You can -recover from this in one of two ways: +aborts in the middle,. You can recover from this in one of two ways: . skip the current patch by re-running the command with '--skip' option. @@ -144,7 +144,7 @@ names. SEE ALSO -------- -gitlink:git-applymbox[1], gitlink:git-applypatch[1], gitlink:git-apply[1]. +gitlink:git-apply[1]. Author @@ -158,4 +158,3 @@ Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.o GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 3bd2c995da..4c7e3a2f7f 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -171,6 +171,20 @@ apply.whitespace:: When no `--whitespace` flag is given from the command line, this configuration item is used as the default. +Submodules +---------- +If the patch contains any changes to submodules then gitlink:git-apply[1] +treats these changes as follows. + +If --index is specified (explicitly or implicitly), then the submodule +commits must match the index exactly for the patch to apply. If any +of the submodules are checked-out, then these check-outs are completely +ignored, i.e., they are not required to be up-to-date or clean and they +are not updated. + +If --index is not specified, then the submodule commits in the patch +are ignored and only the absence of presence of the corresponding +subdirectory is checked and (if possible) updated. Author ------ @@ -183,4 +197,3 @@ Documentation by Junio C Hamano GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-applymbox.txt b/Documentation/git-applymbox.txt deleted file mode 100644 index ea919ba5d7..0000000000 --- a/Documentation/git-applymbox.txt +++ /dev/null @@ -1,98 +0,0 @@ -git-applymbox(1) -================ - -NAME ----- -git-applymbox - Apply a series of patches in a mailbox - - -SYNOPSIS --------- -'git-applymbox' [-u] [-k] [-q] [-m] ( -c .dotest/<num> | <mbox> ) [ <signoff> ] - -DESCRIPTION ------------ -Splits mail messages in a mailbox into commit log message, -authorship information and patches, and applies them to the -current branch. - - -OPTIONS -------- --q:: - Apply patches interactively. The user will be given - opportunity to edit the log message and the patch before - attempting to apply it. - --k:: - Usually the program 'cleans up' the Subject: header line - to extract the title line for the commit log message, - among which (1) remove 'Re:' or 're:', (2) leading - whitespaces, (3) '[' up to ']', typically '[PATCH]', and - then prepends "[PATCH] ". This flag forbids this - munging, and is most useful when used to read back 'git - format-patch -k' output. - --m:: - Patches are applied with `git-apply` command, and unless - it cleanly applies without fuzz, the processing fails. - With this flag, if a tree that the patch applies cleanly - is found in a repository, the patch is applied to the - tree and then a 3-way merge between the resulting tree - and the current tree. - --u:: - Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]). - The proposed commit log message taken from the e-mail - are re-coded into UTF-8 encoding (configuration variable - `i18n.commitencoding` can be used to specify project's - preferred encoding if it is not UTF-8). This used to be - optional but now it is the default. -+ -Note that the patch is always used as-is without charset -conversion, even with this flag. - --n:: - Pass `-n` flag to `git-mailinfo` (see - gitlink:git-mailinfo[1]). - --c .dotest/<num>:: - When the patch contained in an e-mail does not cleanly - apply, the command exits with an error message. The - patch and extracted message are found in .dotest/, and - you could re-run 'git applymbox' with '-c .dotest/<num>' - flag to restart the process after inspecting and fixing - them. - -<mbox>:: - The name of the file that contains the e-mail messages - with patches. This file should be in the UNIX mailbox - format. See 'SubmittingPatches' document to learn about - the formatting convention for e-mail submission. - -<signoff>:: - The name of the file that contains your "Signed-off-by" - line. See 'SubmittingPatches' document to learn what - "Signed-off-by" line means. You can also just say - 'yes', 'true', 'me', or 'please' to use an automatically - generated "Signed-off-by" line based on your committer - identity. - - -SEE ALSO --------- -gitlink:git-am[1], gitlink:git-applypatch[1]. - - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - -GIT ---- -Part of the gitlink:git[7] suite - diff --git a/Documentation/git-applypatch.txt b/Documentation/git-applypatch.txt deleted file mode 100644 index 451434a757..0000000000 --- a/Documentation/git-applypatch.txt +++ /dev/null @@ -1,53 +0,0 @@ -git-applypatch(1) -================= - -NAME ----- -git-applypatch - Apply one patch extracted from an e-mail - - -SYNOPSIS --------- -'git-applypatch' <msg> <patch> <info> [<signoff>] - -DESCRIPTION ------------ -This is usually not what an end user wants to run directly. See -gitlink:git-am[1] instead. - -Takes three files <msg>, <patch>, and <info> prepared from an -e-mail message by 'git-mailinfo', and creates a commit. It is -usually not necessary to use this command directly. - -This command can run `applypatch-msg`, `pre-applypatch`, and -`post-applypatch` hooks. See link:hooks.html[hooks] for more -information. - - -OPTIONS -------- -<msg>:: - Commit log message (sans the first line, which comes - from e-mail Subject stored in <info>). - -<patch>:: - The patch to apply. - -<info>:: - Author and subject information extracted from e-mail, - used on "author" line and as the first line of the - commit log message. - - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - -GIT ---- -Part of the gitlink:git[7] suite - diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index 82cb41d279..7091b8d61c 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -17,26 +17,26 @@ DESCRIPTION Imports a project from one or more Arch repositories. It will follow branches and repositories within the namespaces defined by the <archive/branch> parameters supplied. If it cannot find the remote branch a merge comes from -it will just import it as a regular commit. If it can find it, it will mark it -as a merge whenever possible (see discussion below). +it will just import it as a regular commit. If it can find it, it will mark it +as a merge whenever possible (see discussion below). -The script expects you to provide the key roots where it can start the import -from an 'initial import' or 'tag' type of Arch commit. It will follow and -import new branches within the provided roots. +The script expects you to provide the key roots where it can start the import +from an 'initial import' or 'tag' type of Arch commit. It will follow and +import new branches within the provided roots. -It expects to be dealing with one project only. If it sees -branches that have different roots, it will refuse to run. In that case, -edit your <archive/branch> parameters to define clearly the scope of the -import. +It expects to be dealing with one project only. If it sees +branches that have different roots, it will refuse to run. In that case, +edit your <archive/branch> parameters to define clearly the scope of the +import. -`git-archimport` uses `tla` extensively in the background to access the +`git-archimport` uses `tla` extensively in the background to access the Arch repository. Make sure you have a recent version of `tla` available in the path. `tla` must -know about the repositories you pass to `git-archimport`. +know about the repositories you pass to `git-archimport`. -For the initial import `git-archimport` expects to find itself in an empty -directory. To follow the development of a project that uses Arch, rerun -`git-archimport` with the same parameters as the initial import to perform +For the initial import `git-archimport` expects to find itself in an empty +directory. To follow the development of a project that uses Arch, rerun +`git-archimport` with the same parameters as the initial import to perform incremental imports. While git-archimport will try to create sensible branch names for the @@ -54,15 +54,15 @@ convert Arch repositories that had been rotated periodically. MERGES ------ -Patch merge data from Arch is used to mark merges in git as well. git +Patch merge data from Arch is used to mark merges in git as well. git does not care much about tracking patches, and only considers a merge when a branch incorporates all the commits since the point they forked. The end result -is that git will have a good idea of how far branches have diverged. So the +is that git will have a good idea of how far branches have diverged. So the import process does lose some patch-trading metadata. -Fortunately, when you try and merge branches imported from Arch, -git will find a good merge base, and it has a good chance of identifying -patches that have been traded out-of-sequence between the branches. +Fortunately, when you try and merge branches imported from Arch, +git will find a good merge base, and it has a good chance of identifying +patches that have been traded out-of-sequence between the branches. OPTIONS ------- @@ -71,10 +71,10 @@ OPTIONS Display usage. -v:: - Verbose output. + Verbose output. -T:: - Many tags. Will create a tag for every commit, reflecting the commit + Many tags. Will create a tag for every commit, reflecting the commit name in the Arch repository. -f:: @@ -104,7 +104,7 @@ OPTIONS <archive/branch>:: - Archive/branch identifier in a format that `tla log` understands. + Archive/branch identifier in a format that `tla log` understands. Author @@ -118,4 +118,3 @@ Documentation by Junio C Hamano, Martin Langhoff and the git-list <git@vger.kern GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 4da07c1580..f2080eb6ad 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -72,16 +72,13 @@ zip CONFIGURATION ------------- -By default, file and directories modes are set to 0666 or 0777 in tar -archives. It is possible to change this by setting the "umask" variable -in the repository configuration as follows : -[tar] - umask = 002 ;# group friendly - -The special umask value "user" indicates that the user's current umask -will be used instead. The default value remains 0, which means world -readable/writable files and directories. +tar.umask:: + This variable can be used to restrict the permission bits of + tar archive entries. The default is 0002, which turns off the + world write bit. The special value "user" indicates that the + archiving user's umask will be used instead. See umask(2) for + details. EXAMPLES -------- diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 5f68ee1584..1072fb87d1 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -8,7 +8,7 @@ git-bisect - Find the change that introduced a bug by binary search SYNOPSIS -------- -'git bisect' <subcommand> <options> +'git bisect' <subcommand> <options> DESCRIPTION ----------- @@ -200,4 +200,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 44678b0c36..66f1203701 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -8,7 +8,7 @@ git-blame - Show what revision and author last modified each line of a file SYNOPSIS -------- [verse] -'git-blame' [-c] [-b] [--root] [-s] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] +'git-blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-p] [-w] [--incremental] [-L n,m] [-S <revs-file>] [-M] [-C] [-C] [--since=<date>] [<rev> | --contents <file>] [--] <file> @@ -63,6 +63,11 @@ include::blame-options.txt[] -s:: Suppress author name and timestamp from the output. +-w:: + Ignore whitespace when comparing parent's version and + child's to find where the lines came from. + + THE PORCELAIN FORMAT -------------------- diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 8dc5171f5e..33bc31b0d4 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -41,7 +41,7 @@ to happen. With a `-d` or `-D` option, `<branchname>` will be deleted. You may specify more than one branch for deletion. If the branch currently -has a ref log then the ref log will also be deleted. Use -r together with -d +has a reflog then the reflog will also be deleted. Use -r together with -d to delete remote-tracking branches. @@ -54,9 +54,9 @@ OPTIONS Delete a branch irrespective of its index status. -l:: - Create the branch's ref log. This activates recording of - all changes to made the branch ref, enabling use of date - based sha1 expressions such as "<branchname>@{yesterday}". + Create the branch's reflog. This activates recording of + all changes made to the branch ref, enabling use of date + based sha1 expressions such as "<branchname>@\{yesterday}". -f:: Force the creation of a new branch even if it means deleting @@ -130,12 +130,12 @@ Delete unneeded branch:: ------------ $ git clone git://git.kernel.org/.../git.git my.git $ cd my.git -$ git branch -d -r todo html man <1> -$ git branch -D test <2> +$ 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. @@ -158,4 +158,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 075c0d05ef..afa095c795 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -71,4 +71,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index ceb51959b1..856d2af2ed 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -34,4 +34,3 @@ Documentation by James Bowes. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 6dd6db04bb..b1a8ce110c 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -182,4 +182,3 @@ Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 918d8ee720..734928bf96 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -35,7 +35,7 @@ working tree. OPTIONS ------- -q:: - Quiet, supress feedback messages. + Quiet, suppress feedback messages. -f:: Proceed even if the index or the working tree differs @@ -62,9 +62,9 @@ OPTIONS configuration variable. -l:: - Create the new branch's ref log. This activates recording of - all changes to made the branch ref, enabling use of date - based sha1 expressions such as "<branchname>@{yesterday}". + Create the new branch's reflog. This activates recording of + all changes made to the branch ref, enabling use of date + based sha1 expressions such as "<branchname>@\{yesterday}". -m:: If you have local modifications to one or more files that @@ -215,4 +215,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 68bba98260..47b1e8c2fc 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -68,4 +68,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 8c7d9670d3..e6943822cd 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -67,4 +67,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-citool.txt b/Documentation/git-citool.txt new file mode 100644 index 0000000000..5217ab2234 --- /dev/null +++ b/Documentation/git-citool.txt @@ -0,0 +1,32 @@ +git-citool(1) +============= + +NAME +---- +git-citool - Graphical alternative to git-commit + +SYNOPSIS +-------- +'git citool' + +DESCRIPTION +----------- +A Tcl/Tk based graphical interface to review modified files, stage +them into the index, enter a commit message and record the new +commit onto the current branch. This interface is an alternative +to the less interactive gitlink:git-commit[1] program. + +git-citool is actually a standard alias for 'git gui citool'. +See gitlink:git-gui[1] for more details. + +Author +------ +Written by Shawn O. Pearce <spearce@spearce.org>. + +Documentation +-------------- +Documentation by Shawn O. Pearce <spearce@spearce.org>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index ac938d39df..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:: @@ -64,6 +76,7 @@ OPTIONS Operate quietly. This flag is passed to "rsync" and "git-fetch-pack" commands when given. +--no-checkout:: -n:: No checkout of HEAD is performed after the clone is complete. @@ -106,8 +119,9 @@ OPTIONS as patches. <repository>:: - The (possibly remote) repository to clone from. It can - be any URL git-fetch supports. + The (possibly remote) repository to clone from. See the + <<URLS,URLS>> section below for more information on specifying + repositories. <directory>:: The name of a new directory to clone into. The "humanish" @@ -116,6 +130,8 @@ OPTIONS for "host.xz:foo/.git"). Cloning into an existing directory is not allowed. +include::urls.txt[] + Examples -------- @@ -175,4 +191,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 504a3aa1b4..a2537e179a 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -40,7 +40,7 @@ OPTIONS -p <parent commit>:: Each '-p' indicates the id of a parent commit object. - + Commit Information ------------------ @@ -51,9 +51,9 @@ A commit encapsulates: - author name, email and date - committer name and email and the commit time. -If not provided, "git-commit-tree" uses your name, hostname and domain to -provide author and committer info. This can be overridden by -either `.git/config` file, or using the following environment variables. +While parent object ids are provided on the command line, author and +committer information is taken from the following environment variables, +if set: GIT_AUTHOR_NAME GIT_AUTHOR_EMAIL @@ -65,14 +65,11 @@ either `.git/config` file, or using the following environment variables. (nb "<", ">" and "\n"s are stripped) -In `.git/config` file, the following items are used for GIT_AUTHOR_NAME and -GIT_AUTHOR_EMAIL: - - [user] - name = "Your Name" - email = "your@email.address.xz" +In case (some of) these environment variables are not set, the information +is taken from the configuration items user.name and user.email, or, if not +present, system user name and fully qualified hostname. -A commit comment is read from stdin (max 999 chars). If a changelog +A commit comment is read from stdin. If a changelog entry is not provided via "<" redirection, "git-commit-tree" will just wait for one to be entered and terminated with ^D. @@ -107,4 +104,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 53a7bb0895..e54fb12103 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -8,33 +8,34 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git-commit' [-a | --interactive] [-s] [-v] +'git-commit' [-a | --interactive] [-s] [-v] [-u] [(-c | -C) <commit> | -F <file> | -m <msg> | --amend] [--no-verify] [-e] [--author <author>] [--] [[-i | -o ]<file>...] 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 @@ -71,9 +72,16 @@ OPTIONS Override the author name used in the commit. Use `A U Thor <author@example.com>` format. --m <msg>:: +-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. @@ -115,6 +123,19 @@ but can be used to amend a merge commit. as well. This is usually not what you want unless you are concluding a conflicted merge. +-u|--untracked-files:: + Show all untracked files, also those in uninteresting + directories, in the "Untracked files:" section of commit + message template. Without this option only its name and + a trailing slash are displayed for each untracked + directory. + +-v|--verbose:: + Show unified diff between the HEAD commit and what + would be committed at the bottom of the commit message + template. Note that this diff output doesn't have its + lines prefixed with '#'. + -q|--quiet:: Suppress commit summary message. @@ -231,10 +252,12 @@ on the Subject: line and the rest of the commit in the body. include::i18n.txt[] -ENVIRONMENT VARIABLES ---------------------- -The command specified by either the VISUAL or EDITOR environment -variables is used to edit the commit log message. +ENVIRONMENT AND CONFIGURATION VARIABLES +--------------------------------------- +The editor used to edit the commit log message will be chosen from the +GIT_EDITOR environment variable, the core.editor configuration variable, the +VISUAL environment variable, or the EDITOR environment variable (in that +order). HOOKS ----- diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 387d7bc841..5b794f4399 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] name [value [value_regex]] -'git-config' [--system | --global] --add name value -'git-config' [--system | --global] --replace-all name [value [value_regex]] -'git-config' [--system | --global] [type] --get name [value_regex] -'git-config' [--system | --global] [type] --get-all name [value_regex] -'git-config' [--system | --global] [type] --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] -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 ----------- @@ -37,14 +37,19 @@ prepend a single exclamation mark in front (see also <<EXAMPLES>>). The type specifier can be either '--int' or '--bool', which will make 'git-config' ensure that the variable(s) are of the given type and convert the value to the canonical form (simple decimal number for int, -a "true" or "false" string for bool). Type specifiers currently only -take effect for reading operations. If no type specifier is passed, +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, @@ -94,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. @@ -118,13 +126,21 @@ See also <<FILES>>. in the config file will cause the value to be multiplied by 1024, 1048576, or 1073741824 prior to output. +-z, --null:: + For all options that output values and/or keys, always + end values with with the null character (instead of a + newline). Use newline instead as a delimiter between + key and value. This allows for secure parsing of the + output without getting confused e.g. by values that + contain line breaks. + [[FILES]] FILES ----- -There are three files where git-config will search for configuration -options: +If not set explicitly with '--file', there are three files where +git-config will search for configuration options: .git/config:: Repository specific configuration file. (The filename is @@ -198,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 @@ -275,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' ------------ @@ -293,4 +307,3 @@ Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.ker GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-convert-objects.txt b/Documentation/git-convert-objects.txt index b1220c06e1..9718abf86d 100644 --- a/Documentation/git-convert-objects.txt +++ b/Documentation/git-convert-objects.txt @@ -26,4 +26,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 91c8c92c76..81614111a4 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -35,4 +35,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index f3590dee04..4c8d1e6386 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -8,25 +8,25 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- -'git-cvsexportcommit' [-h] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID +'git-cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID DESCRIPTION ----------- Exports a commit from GIT to a CVS checkout, making it easier -to merge patches from a git repository into a CVS repository. +to merge patches from a git repository into a CVS repository. -Execute it from the root of the CVS working copy. GIT_DIR must be defined. +Execute it from the root of the CVS working copy. GIT_DIR must be defined. See examples below. -It does its best to do the safe thing, it will check that the files are -unchanged and up to date in the CVS checkout, and it will not autocommit +It does its best to do the safe thing, it will check that the files are +unchanged and up to date in the CVS checkout, and it will not autocommit by default. Supports file additions, removals, and commits that affect binary files. If the commit is a merge commit, you must tell git-cvsexportcommit what parent -should the changeset be done against. +should the changeset be done against. OPTIONS ------- @@ -55,9 +55,12 @@ OPTIONS Force the parent commit, even if it is not a direct parent. -m:: - Prepend the commit message with the provided prefix. + Prepend the commit message with the provided prefix. Useful for patch series and the like. +-u:: + Update affected files from CVS repository before attempting export. + -v:: Verbose. @@ -70,7 +73,7 @@ Merge one patch into CVS:: $ export GIT_DIR=~/project/.git $ cd ~/project_cvs_checkout $ git-cvsexportcommit -v <commit-sha1> -$ cvs commit -F .mgs <files> +$ cvs commit -F .mgs <files> ------------ Merge pending patches into CVS automatically -- only if you really know what you are doing:: @@ -92,4 +95,3 @@ Documentation by Martin Langhoff <martin@catalyst.net.nz> GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index e0be856546..fdd7ec7edd 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -13,7 +13,7 @@ SYNOPSIS [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] - [<CVS_module>] + [-r <remote>] [<CVS_module>] DESCRIPTION @@ -25,10 +25,12 @@ Splitting the CVS log into patch sets is done by 'cvsps'. At least version 2.1 is required. You should *never* do any work of your own on the branches that are -created by git-cvsimport. The initial import will create and populate a +created by git-cvsimport. By default initial import will create and populate a "master" branch from the CVS repository's main branch which you're free to work with; after that, you need to 'git merge' incremental imports, or -any CVS branches, yourself. +any CVS branches, yourself. It is advisable to specify a named remote via +-r to separate and protect the incoming branches. + OPTIONS ------- @@ -37,7 +39,7 @@ OPTIONS -d <CVSROOT>:: The root of the CVS archive. May be local (a simple path) or remote; - currently, only the :local:, :ext: and :pserver: access methods + currently, only the :local:, :ext: and :pserver: access methods are supported. If not given, git-cvsimport will try to read it from `CVS/Root`. If no such file exists, it checks for the `CVSROOT` environment variable. @@ -51,10 +53,19 @@ OPTIONS The git repository to import to. If the directory doesn't exist, it will be created. Default is the current directory. +-r <remote>:: + The git remote to import this CVS repository into. + Moves all CVS branches into remotes/<remote>/<branch> + akin to the git-clone --use-separate-remote option. + -o <branch-for-HEAD>:: - The 'HEAD' branch from CVS is imported to the 'origin' branch within - the git repository, as 'HEAD' already has a special meaning for git. - Use this option if you want to import into a different branch. + When no remote is specified (via -r) the 'HEAD' branch + from CVS is imported to the 'origin' branch within the git + repository, as 'HEAD' already has a special meaning for git. + When a remote is specified the 'HEAD' branch is named + remotes/<remote>/master mirroring git-clone behaviour. + Use this option if you want to import into a different + branch. + Use '-o master' for continuing an import that was initially done by the old cvs2git tool. @@ -67,7 +78,7 @@ the old cvs2git tool. -k:: Kill keywords: will extract files with '-kk' from the CVS archive to avoid noisy changesets. Highly recommended, but off by default - to preserve compatibility with early imported trees. + to preserve compatibility with early imported trees. -u:: Convert underscores in tag and branch names to dots. @@ -89,15 +100,15 @@ If you need to pass multiple options, separate them with a comma. Instead of calling cvsps, read the provided cvsps output file. Useful for debugging or when cvsps is being handled outside cvsimport. --m:: +-m:: Attempt to detect merges based on the commit message. This option - will enable default regexes that try to capture the name source - branch name from the commit message. + will enable default regexes that try to capture the name source + branch name from the commit message. -M <regex>:: Attempt to detect merges based on the commit message with a custom regex. It can be used with '-m' to also see the default regexes. - You must escape forward slashes. + You must escape forward slashes. -S <regex>:: Skip paths matching the regex. @@ -156,4 +167,3 @@ Documentation by Matthias Urlichs <smurf@smurf.noris.de>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index e5005f02f9..258a62f7e9 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -7,10 +7,53 @@ git-cvsserver - A CVS server emulator for git SYNOPSIS -------- + +SSH: + [verse] export CVS_SERVER=git-cvsserver 'cvs' -d :ext:user@server/path/repo.git co <HEAD_name> +pserver (/etc/inetd.conf): + +[verse] +cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver + +Usage: + +[verse] +'git-cvsserver' [options] [pserver|server] [<directory> ...] + +OPTIONS +------- + +All these options obviously only make sense if enforced by the server side. +They have been implemented to resemble the gitlink:git-daemon[1] options as +closely as possible. + +--base-path <path>:: +Prepend 'path' to requested CVSROOT + +--strict-paths:: +Don't allow recursing into subdirectories + +--export-all:: +Don't check for `gitcvs.enabled` in config. You also have to specify a list +of allowed directories (see below) if you want to use this option. + +--version, -V:: +Print version information and exit + +--help, -h, -H:: +Print usage information and exit + +<directory>:: +You can specify a list of allowed directories. If no directories +are given, all are allowed. This is an additional restriction, gitcvs +access still needs to be enabled by the `gitcvs.enabled` config option +unless '--export-all' was given, too. + + DESCRIPTION ----------- @@ -59,7 +102,7 @@ No special setup is needed for SSH access, other than having GIT tools in the PATH. If you have clients that do not accept the CVS_SERVER environment variable, you can rename git-cvsserver to cvs. -Note: Newer cvs versions (>= 1.12.11) also support specifying +Note: Newer CVS versions (>= 1.12.11) also support specifying CVS_SERVER directly in CVSROOT like ------ diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 9ddab71203..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 @@ -235,4 +241,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 47a583d3a6..ac23e28f27 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -8,7 +8,7 @@ git-describe - Show the most recent tag that is reachable from a commit SYNOPSIS -------- -'git-describe' [--all] [--tags] [--abbrev=<n>] <committish>... +'git-describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>... DESCRIPTION ----------- @@ -31,6 +31,11 @@ OPTIONS Instead of using only the annotated tags, use any tag found in `.git/refs/tags`. +--contains:: + Instead of finding the tag that predates the commit, find + the tag that comes after the commit, and thus contains it. + Automatically implies --tags. + --abbrev=<n>:: Instead of using the default 8 hexadecimal digits as the abbreviated object name, use <n> digits. @@ -119,4 +124,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index 2e1e29ef5a..d8a0a86022 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -26,7 +26,7 @@ include::diff-options.txt[] branch" respectively. With these options, diffs for merged entries are not shown. + -The default is to diff against our branch (-2) and the +The default is to diff against our branch (-2) and the cleanly resolved paths. The option -0 can be given to omit diff output for unmerged entries and just show "Unmerged". @@ -58,4 +58,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 2df581c2c9..7bd262cefd 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -75,7 +75,7 @@ actually doing a "git-write-tree" and comparing that. Except this one is much nicer for the case where you just want to check where you are. So doing a "git-diff-index --cached" is basically very useful when you are -asking yourself "what have I already marked for being committed, and +asking yourself "what have I already marked for being committed, and what's the difference to a previous tree". Non-cached Mode @@ -130,4 +130,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 6e660e2d08..6b3f74efe7 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -166,4 +166,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 044cee9b42..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 @@ -138,4 +135,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 87e70fe12d..d5119678b5 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -176,6 +176,15 @@ results, such as branch names or file names with leading or trailing spaces in their name, or early termination of fast-import when it encounters unexpected input. +Stream Comments +~~~~~~~~~~~~~~~ +To aid in debugging frontends fast-import ignores any line that +begins with `#` (ASCII pound/hash) up to and including the line +ending `LF`. A comment line may contain any sequence of bytes +that does not contain an LF and therefore may be used to include +any detailed debugging information that might be specific to the +frontend and useful when inspecting a fast-import data stream. + Date Formats ~~~~~~~~~~~~ The following date formats are supported. A frontend should select @@ -232,7 +241,7 @@ been well tested in the wild. + Frontends should prefer the `raw` format if the source material already uses UNIX-epoch format, can be coaxed to give dates in that -format, or its format is easiliy convertible to it, as there is no +format, or its format is easily convertible to it, as there is no ambiguity in parsing. `now`:: @@ -289,6 +298,11 @@ and control the current import process. More detailed discussion This command is optional and is not needed to perform an import. +`progress`:: + Causes fast-import to echo the entire line to its own + standard output. This command is optional and is not needed + to perform an import. + `commit` ~~~~~~~~ Create or update a branch with a new commit, recording one logical @@ -302,8 +316,8 @@ change to the project. data ('from' SP <committish> LF)? ('merge' SP <committish> LF)? - (filemodify | filedelete | filedeleteall)* - LF + (filemodify | filedelete | filecopy | filerename | filedeleteall)* + LF? .... where `<ref>` is the name of the branch to make the commit on. @@ -325,13 +339,17 @@ commit message use a 0 length data. Commit messages are free-form and are not interpreted by Git. Currently they must be encoded in UTF-8, as fast-import does not permit other encodings to be specified. -Zero or more `filemodify`, `filedelete` and `filedeleteall` commands +Zero or more `filemodify`, `filedelete`, `filecopy`, `filerename` +and `filedeleteall` commands may be included to update the contents of the branch prior to creating the commit. These commands may be supplied in any order. -However it is recommended that a `filedeleteall` command preceed -all `filemodify` commands in the same commit, as `filedeleteall` +However it is recommended that a `filedeleteall` command precede +all `filemodify`, `filecopy` and `filerename` commands in the same +commit, as `filedeleteall` wipes the branch clean (see below). +The `LF` after the command is optional (it used to be required). + `author` ^^^^^^^^ An `author` command may optionally appear, if the author information @@ -384,7 +402,7 @@ Here `<committish>` is any of the following: + The reason fast-import uses `:` to denote a mark reference is this character is not legal in a Git branch name. The leading `:` makes it easy -to distingush between the mark 42 (`:42`) and the branch 42 (`42` +to distinguish between the mark 42 (`:42`) and the branch 42 (`42` or `refs/heads/42`), or an abbreviated SHA-1 which happened to consist only of base-10 digits. + @@ -469,7 +487,7 @@ start with double quote (`"`). If an `LF` or double quote must be encoded into `<path>` shell-style quoting should be used, e.g. `"path/with\n and \" in it"`. -The value of `<path>` must be in canoncial form. That is it must not: +The value of `<path>` must be in canonical form. That is it must not: * contain an empty directory component (e.g. `foo//bar` is invalid), * end with a directory separator (e.g. `foo/` is invalid), @@ -495,6 +513,56 @@ here `<path>` is the complete path of the file or subdirectory to be removed from the branch. See `filemodify` above for a detailed description of `<path>`. +`filecopy` +^^^^^^^^^^^^ +Recursively copies an existing file or subdirectory to a different +location within the branch. The existing file or directory must +exist. If the destination exists it will be completely replaced +by the content copied from the source. + +.... + 'C' SP <path> SP <path> LF +.... + +here the first `<path>` is the source location and the second +`<path>` is the destination. See `filemodify` above for a detailed +description of what `<path>` may look like. To use a source path +that contains SP the path must be quoted. + +A `filecopy` command takes effect immediately. Once the source +location has been copied to the destination any future commands +applied to the source location will not impact the destination of +the copy. + +`filerename` +^^^^^^^^^^^^ +Renames an existing file or subdirectory to a different location +within the branch. The existing file or directory must exist. If +the destination exists it will be replaced by the source directory. + +.... + 'R' SP <path> SP <path> LF +.... + +here the first `<path>` is the source location and the second +`<path>` is the destination. See `filemodify` above for a detailed +description of what `<path>` may look like. To use a source path +that contains SP the path must be quoted. + +A `filerename` command takes effect immediately. Once the source +location has been renamed to the destination any future commands +applied to the source location will create new files there and not +impact the destination of the rename. + +Note that a `filerename` is the same as a `filecopy` followed by a +`filedelete` of the source location. There is a slight performance +advantage to using `filerename`, but the advantage is so small +that it is never worth trying to convert a delete/add pair in +source material into a rename for fast-import. This `filerename` +command is provided just to simplify frontends that already have +rename information and don't want bother with decomposing it into a +`filecopy` followed by a `filedelete`. + `filedeleteall` ^^^^^^^^^^^^^^^ Included in a `commit` command to remove all files (and also all @@ -593,12 +661,14 @@ branch from an existing commit without creating a new commit. .... 'reset' SP <ref> LF ('from' SP <committish> LF)? - LF + LF? .... For a detailed description of `<ref>` and `<committish>` see above under `commit` and `from`. +The `LF` after the command is optional (it used to be required). + The `reset` command can also be used to create lightweight (non-annotated) tags. For example: @@ -637,29 +707,40 @@ intended for production-quality conversions should always use the exact byte count format, as it is more robust and performs better. The delimited format is intended primarily for testing fast-import. +Comment lines appearing within the `<raw>` part of `data` commands +are always taken to be part of the body of the data and are therefore +never ignored by fast-import. This makes it safe to import any +file/message content whose lines might start with `#`. + Exact byte count format:: The frontend must specify the number of bytes of data. + .... 'data' SP <count> LF - <raw> LF + <raw> LF? .... + where `<count>` is the exact number of bytes appearing within `<raw>`. The value of `<count>` is expressed as an ASCII decimal integer. The `LF` on either side of `<raw>` is not included in `<count>` and will not be included in the imported data. ++ +The `LF` after `<raw>` is optional (it used to be required) but +recommended. Always including it makes debugging a fast-import +stream easier as the next command always starts in column 0 +of the next line, even if `<raw>` did not end with an `LF`. Delimited format:: A delimiter string is used to mark the end of the data. fast-import will compute the length by searching for the delimiter. - This format is primarly useful for testing and is not + This format is primarily useful for testing and is not recommended for real data. + .... 'data' SP '<<' <delim> LF <raw> LF <delim> LF + LF? .... + where `<delim>` is the chosen delimiter string. The string `<delim>` @@ -668,6 +749,8 @@ fast-import will think the data ends earlier than it really does. The `LF` immediately trailing `<raw>` is part of `<raw>`. This is one of the limitations of the delimited format, it is impossible to supply a data chunk which does not have an LF as its last byte. ++ +The `LF` after `<delim> LF` is optional (it used to be required). `checkpoint` ~~~~~~~~~~~~ @@ -676,7 +759,7 @@ save out all current branch refs, tags and marks. .... 'checkpoint' LF - LF + LF? .... Note that fast-import automatically switches packfiles when the current @@ -695,6 +778,32 @@ process access to a branch. However given that a 30 GiB Subversion repository can be loaded into Git through fast-import in about 3 hours, explicit checkpointing may not be necessary. +The `LF` after the command is optional (it used to be required). + +`progress` +~~~~~~~~~~ +Causes fast-import to print the entire `progress` line unmodified to +its standard output channel (file descriptor 1) when the command is +processed from the input stream. The command otherwise has no impact +on the current import, or on any of fast-import's internal state. + +.... + 'progress' SP <any> LF + LF? +.... + +The `<any>` part of the command may contain any sequence of bytes +that does not contain `LF`. The `LF` after the command is optional. +Callers may wish to process the output through a tool such as sed to +remove the leading part of the line, for example: + +==== + frontend | git-fast-import | sed 's/^progress //' +==== + +Placing a `progress` command immediately after a `checkpoint` will +inform the reader when the `checkpoint` has been completed and it +can safely access the refs that fast-import updated. Tips and Tricks --------------- @@ -764,7 +873,7 @@ to remove the dummy branch. Import Now, Repack Later ~~~~~~~~~~~~~~~~~~~~~~~~ As soon as fast-import completes the Git repository is completely valid -and ready for use. Typicallly this takes only a very short time, +and ready for use. Typically this takes only a very short time, even for considerably large projects (100,000+ commits). However repacking the repository is necessary to improve data @@ -788,6 +897,15 @@ This will take longer, but will also produce a smaller packfile. You only need to expend the effort once, and everyone using your project will benefit from the smaller repository. +Include Some Progress Messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Every once in a while have your frontend emit a `progress` message +to fast-import. The contents of the messages are entirely free-form, +so one suggestion would be to output the current month and year +each time the current commit date moves into the next month. +Your users will feel better knowing how much of the data stream +has been processed. + Packfile Optimization --------------------- @@ -824,8 +942,8 @@ Memory Utilization ------------------ There are a number of factors which affect how much memory fast-import requires to perform an import. Like critical sections of core -Git, fast-import uses its own memory allocators to ammortize any overheads -associated with malloc. In practice fast-import tends to ammoritize any +Git, fast-import uses its own memory allocators to amortize any overheads +associated with malloc. In practice fast-import tends to amortize any malloc overheads to 0, due to its use of large block allocations. per object @@ -882,7 +1000,7 @@ per active tree ~~~~~~~~~~~~~~~ Trees (aka directories) use just 12 bytes of memory on top of the memory required for their entries (see ``per active file'' below). -The cost of a tree is virtually 0, as its overhead ammortizes out +The cost of a tree is virtually 0, as its overhead amortizes out over the individual file entries. per active file entry @@ -910,4 +1028,3 @@ Documentation by Shawn O. Pearce <spearce@spearce.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 5fbeab76b7..9003473596 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -35,7 +35,7 @@ include::fetch-options.txt[] include::pull-fetch-param.txt[] -include::urls.txt[] +include::urls-remotes.txt[] SEE ALSO -------- diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt new file mode 100644 index 0000000000..8c43be611a --- /dev/null +++ b/Documentation/git-filter-branch.txt @@ -0,0 +1,278 @@ +git-filter-branch(1) +==================== + +NAME +---- +git-filter-branch - Rewrite branches + +SYNOPSIS +-------- +[verse] +'git-filter-branch' [--env-filter <command>] [--tree-filter <command>] + [--index-filter <command>] [--parent-filter <command>] + [--msg-filter <command>] [--commit-filter <command>] + [--tag-name-filter <command>] [--subdirectory-filter <directory>] + [-d <directory>] [-f | --force] [<rev-list options>...] + +DESCRIPTION +----------- +Lets you rewrite git revision history by creating a new branch from +your current branch, applying custom filters on each revision. +Those filters can modify each tree (e.g. removing a file or running +a perl rewrite on all files) or information about each commit. +Otherwise, all information (including original commit times or merge +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. 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 +be able to easily push and distribute the rewritten branch on top of the +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: 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 +tmpfs. Reportedly the speedup is very noticeable. + + +Filters +~~~~~~~ + +The filters are applied in the order as listed below. The <command> +argument is always evaluated in shell using the 'eval' command (with the +notable exception of the commit filter, for technical reasons). +Prior to that, the $GIT_COMMIT environment variable will be set to contain +the id of the commit being rewritten. Also, GIT_AUTHOR_NAME, +GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, +and GIT_COMMITTER_DATE are set according to the current commit. + +A 'map' function is available that takes an "original sha1 id" argument +and outputs a "rewritten sha1 id" if the commit has been already +rewritten, and "original sha1 id" otherwise; the 'map' function can +return several ids on separate lines if your commit filter emitted +multiple commits. + + +OPTIONS +------- + +--env-filter <command>:: + This is the filter for modifying the environment in which + the commit will be performed. Specifically, you might want + to rewrite the author/committer name/email/time environment + variables (see gitlink:git-commit[1] for details). Do not forget + to re-export the variables. + +--tree-filter <command>:: + This is the filter for rewriting the tree and its contents. + The argument is evaluated in shell with the working + directory set to the root of the checked out tree. The new tree + is then used as-is (new files are auto-added, disappeared files + are auto-removed - neither .gitignore files nor any other ignore + rules *HAVE ANY EFFECT*!). + +--index-filter <command>:: + This is the filter for rewriting the index. It is similar to the + tree filter but does not check out the tree, which makes it much + faster. For hairy cases, see gitlink:git-update-index[1]. + +--parent-filter <command>:: + This is the filter for rewriting the commit's parent list. + It will receive the parent string on stdin and shall output + the new parent string on stdout. The parent string is in + a format accepted by gitlink:git-commit-tree[1]: empty for + the initial commit, "-p parent" for a normal commit and + "-p parent1 -p parent2 -p parent3 ..." for a merge commit. + +--msg-filter <command>:: + This is the filter for rewriting the commit messages. + The argument is evaluated in the shell with the original + commit message on standard input; its standard output is + used as the new commit message. + +--commit-filter <command>:: + This is the filter for performing the commit. + If this filter is specified, it will be called instead of the + gitlink:git-commit-tree[1] command, with arguments of the form + "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on + stdin. The commit id is expected on stdout. ++ +As a special extension, the commit filter may emit multiple +commit ids; in that case, ancestors of the original commit will +have all of them as parents. + +--tag-name-filter <command>:: + This is the filter for rewriting tag names. When passed, + it will be called for every tag ref that points to a rewritten + object (or to a tag object which points to a rewritten object). + The original tag name is passed via standard input, and the new + tag name is expected on standard output. ++ +The original tags are not deleted, but can be overwritten; +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.) + +--subdirectory-filter <directory>:: + Only look at the history which touches the given subdirectory. + The result will contain that directory (and only that) as its + project root. + +-d <directory>:: + Use this option to set the path to the temporary directory used for + rewriting. When applying a tree filter, the command needs to + temporary checkout the tree to some directory, which may consume + considerable space in case of large projects. By default it + 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 + output will be filtered, although the filtered commits can still + reference parents which are outside of that set. + + +Examples +-------- + +Suppose you want to remove a file (containing confidential information +or copyright violation) from all commits: + +------------------------------------------------------- +git filter-branch --tree-filter 'rm filename' HEAD +------------------------------------------------------- + +A significantly faster version: + +-------------------------------------------------------------------------- +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). + +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>/"' 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>"' HEAD +-------------------------------------------------------------------------- + +or even simpler: + +----------------------------------------------- +echo "$commit-id $graft-id" >> .git/info/grafts +git filter-branch $graft-id..HEAD +----------------------------------------------- + +To remove commits authored by "Darl McBribe" from the history: + +------------------------------------------------------------------------------ +git filter-branch --commit-filter ' + if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ]; + then + shift; + while [ -n "$1" ]; + do + shift; + echo "$1"; + shift; + done; + else + git commit-tree "$@"; + fi' HEAD +------------------------------------------------------------------------------ + +The shift magic first throws away the tree id and then the -p +parameters. Note that this handles merges properly! In case Darl +committed a merge between P1 and P2, it will be propagated properly +and all children of the merge will become merge commits with P1,P2 +as their parents instead of the merge commit. + +To restrict rewriting to only part of the history, specify a revision +range in addition to the new branch name. The new branch name will +point to the top-most revision that a 'git rev-list' of this range +will print. + +Note that the changes introduced by the commits, and not reverted by +subsequent commits, will still be in the rewritten branch. If you want +to throw out _changes_ together with the commits, you should use the +interactive mode of gitlink:git-rebase[1]. + +Consider this history: + +------------------ + D--E--F--G--H + / / +A--B-----C +------------------ + +To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use: + +-------------------------------- +git filter-branch ... C..H +-------------------------------- + +To rewrite commits E,F,G,H, use one of these: + +---------------------------------------- +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: + +--------------------------------------------------------------- +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' HEAD +--------------------------------------------------------------- + + +Author +------ +Written by Petr "Pasky" Baudis <pasky@suse.cz>, +and the git list <git@vger.kernel.org> + +Documentation +-------------- +Documentation by Petr Baudis and the git list. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 4913c2552f..7088ed4095 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] git-fmt-merge-msg [--summary | --no-summary] <$GIT_DIR/FETCH_HEAD -git-fmt-merge-msg [--summary | --no-summray] -F <file> +git-fmt-merge-msg [--summary | --no-summary] -F <file> DESCRIPTION ----------- @@ -60,4 +60,3 @@ Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.o GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 0ca58a7eb3..c514fdd93f 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -11,7 +11,8 @@ SYNOPSIS [verse] 'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--thread] [--attach[=<boundary>] | --inline[=<boundary>]] - [-s | --signoff] [<common diff options>] [--start-number <n>] + [-s | --signoff] [<common diff options>] + [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] @@ -30,9 +31,11 @@ gitlink:git-rev-parse[1]. The output of this command is convenient for e-mail submission or for use with gitlink:git-am[1]. -Each output file is numbered sequentially from 1, and uses the +By default, each output file is numbered sequentially from 1, and uses the first line of the commit message (massaged for pathname safety) as -the filename. The names of the output files are printed to standard +the filename. With the --numbered-files option, the output file names +will only be numbers, without the first line of the commit appended. +The names of the output files are printed to standard output, unless the --stdout option is specified. If -o is specified, output files are created in <dir>. Otherwise @@ -63,6 +66,11 @@ include::diff-options.txt[] --start-number <n>:: Start numbering the patches at <n> instead of 1. +--numbered-files:: + Output file names will be a simple number sequence + without the default first line of the commit appended. + Mutually exclusive with the --stdout option. + -k|--keep-subject:: Do not strip/add '[PATCH]' from the first line of the commit log message. @@ -110,7 +118,7 @@ include::diff-options.txt[] --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated - filenames, use specifed suffix. A common alternative is + filenames, use specified suffix. A common alternative is `--suffix=.txt`. + Note that you would need to include the leading dot `.` if you @@ -121,12 +129,13 @@ not add any suffix. CONFIGURATION ------------- You can specify extra mail header lines to be added to each -message in the repository configuration. Also you can specify -the default suffix different from the built-in one: +message in the repository configuration. You can also specify +new defaults for the subject prefix and file suffix. ------------ [format] headers = "Organization: git-foo\n" + subjectprefix = CHANGE suffix = .txt ------------ @@ -173,4 +182,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 8c68cf0372..45c0bee50a 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git-fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] - [--full] [--strict] [<object>*] + [--full] [--strict] [--verbose] [--lost-found] [<object>*] DESCRIPTION ----------- @@ -61,6 +61,15 @@ index file and all SHA1 references in .git/refs/* as heads. objects that triggers this check, but it is recommended to check new projects with this flag. +--verbose:: + Be chatty. + +--lost-found:: + 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 corruption it finds (missing or bad objects), and if you use the @@ -142,4 +151,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index bc1658434a..c7742ca963 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -8,7 +8,7 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- -'git-gc' [--prune] +'git-gc' [--prune] [--aggressive] DESCRIPTION ----------- @@ -35,6 +35,13 @@ OPTIONS repository at the same time (e.g. never use this option in a cron script). +--aggressive:: + Usually 'git-gc' runs very quickly while providing good disk + space utilization and performance. This option will cause + git-gc to more aggressively optimize the repository at the expense + of taking much more time. The effects of this optimization are + persistent, so this option only needs to be used occasionally; every + few hundred changesets or so. Configuration ------------- @@ -67,6 +74,13 @@ The optional configuration variable 'gc.packrefs' determines if is not run in bare repositories by default, to allow older dumb-transport clients fetch from the repository, but this will change in the future. +The optional configuration variable 'gc.aggressiveWindow' controls how +much time is spent optimizing the delta compression of the objects in +the repository when the --aggressive option is specified. The larger +the value, the more time is spent optimizing the delta compression. See +the documentation for the --window' option in gitlink:git-repack[1] for +more details. This defaults to 10. + See Also -------- gitlink:git-prune[1] diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index 48805b651c..9b5f86fc30 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -34,4 +34,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index c5a5dad1ce..97faaa1d3a 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -144,4 +144,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt new file mode 100644 index 0000000000..13252a1aa6 --- /dev/null +++ b/Documentation/git-gui.txt @@ -0,0 +1,115 @@ +git-gui(1) +========== + +NAME +---- +git-gui - A portable graphical interface to Git + +SYNOPSIS +-------- +'git gui' [<command>] [arguments] + +DESCRIPTION +----------- +A Tcl/Tk based graphical user interface to Git. git-gui focuses +on allowing users to make changes to their repository by making +new commits, amending existing ones, creating branches, performing +local merges, and fetching/pushing to remote repositories. + +Unlike gitlink:gitk[1], git-gui focuses on commit generation +and single file annotation, and does not show project history. +It does however supply menu actions to start a gitk session from +within git-gui. + +git-gui is known to work on all popular UNIX systems, Mac OS X, +and Windows (under both Cygwin and MSYS). To the extent possible +OS specific user interface guidelines are followed, making git-gui +a fairly native interface for users. + +COMMANDS +-------- +blame:: + Start a blame viewer on the specified file on the given + version (or working directory if not specified). + +browser:: + Start a tree browser showing all files in the specified + commit (or 'HEAD' by default). Files selected through the + browser are opened in the blame viewer. + +citool:: + Start git-gui and arrange to make exactly one commit before + exiting and returning to the shell. The interface is limited + to only commit actions, slightly reducing the application's + startup time and simplifying the menubar. + +version:: + Display the currently running version of git-gui. + + +Examples +-------- +git gui blame Makefile:: + + Show the contents of the file 'Makefile' in the current + working directory, and provide annotations for both the + original author of each line, and who moved the line to its + current location. The uncommitted file is annotated, and + uncommitted changes (if any) are explicitly attributed to + 'Not Yet Committed'. + +git gui blame v0.99.8 Makefile:: + + Show the contents of 'Makefile' in revision 'v0.99.8' + and provide annotations for each line. Unlike the above + example the file is read from the object database and not + the working directory. + +git gui citool:: + + Make one commit and return to the shell when it is complete. + +git citool:: + + Same as 'git gui citool' (above). + +git gui browser maint:: + + Show a browser for the tree of the 'maint' branch. Files + selected in the browser can be viewed with the internal + blame viewer. + +See Also +-------- +'gitk(1)':: + The git repository browser. Shows branches, commit history + and file differences. gitk is the utility started by + git-gui's Repository Visualize actions. + +Other +----- +git-gui is actually maintained as an independent project, but stable +versions are distributed as part of the Git suite for the convenience +of end users. + +A git-gui development repository can be obtained from: + + git clone git://repo.or.cz/git-gui.git + +or + + git clone http://repo.or.cz/r/git-gui.git + +or browsed online at http://repo.or.cz/w/git-gui.git/[]. + +Author +------ +Written by Shawn O. Pearce <spearce@spearce.org>. + +Documentation +-------------- +Documentation by Shawn O. Pearce <spearce@spearce.org>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 5edc36f060..616f196d81 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -18,7 +18,7 @@ work tree), and optionally writes the resulting object into the object database. Reports its object ID to its standard output. This is used by "git-cvsimport" to update the index without modifying files in the work tree. When <type> is not -specified, it defaults to "blob". +specified, it defaults to "blob". OPTIONS ------- @@ -43,4 +43,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index 4deabc376c..389c6edfb8 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -34,7 +34,7 @@ commit-id:: the local end after the transfer is complete. --stdin:: - Instead of a commit id on the commandline (which is not expected in this + Instead of a commit id on the command line (which is not expected in this case), 'git-http-fetch' expects lines on stdin in the format <commit-id>['\t'<filename-as-in--w>] @@ -54,4 +54,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index a15cf5b2a3..9afb860381 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -52,7 +52,7 @@ Specifying the Refs A '<ref>' specification can be either a single pattern, or a pair of such patterns separated by a colon ":" (this means that a ref name -cannot have a colon in it). A single pattern '<name>' is just a +cannot have a colon in it). A single pattern '<name>' is just a shorthand for '<name>:<name>'. Each pattern pair consists of the source side (before the colon) diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 226926964e..a8a7f6f04b 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -98,4 +98,3 @@ Documentation by Sergey Vlasov GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 5412135d76..d4e01cb325 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -8,7 +8,7 @@ git-init-db - Creates an empty git repository SYNOPSIS -------- -'git-init-db' [--template=<template_directory>] [--shared[=<permissions>]] +'git-init-db' [-q | --quiet] [--template=<template_directory>] [--shared[=<permissions>]] DESCRIPTION @@ -16,4 +16,3 @@ DESCRIPTION This is a synonym for gitlink:git-init[1]. Please refer to the documentation of that command. - diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 1b64d3ab03..07484a4fd0 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -8,7 +8,7 @@ git-init - Create an empty git repository or reinitialize an existing one SYNOPSIS -------- -'git-init' [--template=<template_directory>] [--shared[=<permissions>]] +'git-init' [-q | --quiet] [--template=<template_directory>] [--shared[=<permissions>]] OPTIONS @@ -16,6 +16,10 @@ OPTIONS -- +-q, \--quiet:: + +Only print error and warning messages, all other output will be suppressed. + --template=<template_directory>:: Provide the directory from which templates will be used. The default template @@ -108,4 +112,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index 9df0ab2d76..cec60ee780 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -82,4 +82,3 @@ Documentation by Eric Wong <normalperson@yhbt.net>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-local-fetch.txt b/Documentation/git-local-fetch.txt index 51389ef37d..e830deeff3 100644 --- a/Documentation/git-local-fetch.txt +++ b/Documentation/git-local-fetch.txt @@ -14,6 +14,8 @@ SYNOPSIS DESCRIPTION ----------- +THIS COMMAND IS DEPRECATED. + Duplicates another git repository on a local system. OPTIONS @@ -42,7 +44,7 @@ OPTIONS the local end after the transfer is complete. --stdin:: - Instead of a commit id on the commandline (which is not expected in this + Instead of a commit id on the command line (which is not expected in this case), 'git-local-fetch' expects lines on stdin in the format <commit-id>['\t'<filename-as-in--w>] @@ -62,4 +64,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 0f353f6558..1e6dbd93b1 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -49,10 +49,28 @@ include::pretty-options.txt[] -g, \--walk-reflogs:: Show commits as they were recorded in the reflog. The log contains a record about how the tip of a reference was changed. + Cannot be combined with --reverse. See also gitlink:git-reflog[1]. --decorate:: - Print out the ref names of any commits that are shown. + Print out the ref names of any commits that are shown. + +--full-diff:: + Without this flag, "git log -p <paths>..." shows commits that + touch the specified paths, and diffs about the same specified + paths. With this, the full diff is shown for commits that touch + the specified paths; this means that "<paths>..." limits only + commits, and doesn't limit diff for those commits. + +--follow:: + Continue listing the history of a file beyond renames. + +--log-size:: + Before the log message print out its size in bytes. Intended + mainly for porcelain tools consumption. If git is unable to + produce a valid value size is set to zero. + Note that only message is considered, if also a diff is shown + its size is not included. <paths>...:: Show only commits that affect the specified paths. @@ -84,6 +102,12 @@ git log -r --name-status release..test:: in the "release" branch, along with the list of paths each commit modifies. +git log --follow builtin-rev-list.c:: + + Shows the commits that changed builtin-rev-list.c, including + those commits that occurred before the file was given its + present name. + Discussion ---------- @@ -101,4 +125,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index a78a9ff1b8..997594549f 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -180,4 +180,3 @@ Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index c254005ca3..93e9a60330 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -70,4 +70,3 @@ Written by Junio C Hamano <junkio@cox.net> GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 7899394081..7b78599673 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -9,7 +9,7 @@ git-ls-tree - List the contents of a tree object SYNOPSIS -------- [verse] -'git-ls-tree' [-d] [-r] [-t] [-z] +'git-ls-tree' [-d] [-r] [-t] [-l] [-z] [--name-only] [--name-status] [--full-name] [--abbrev=[<n>]] <tree-ish> [paths...] @@ -36,6 +36,10 @@ OPTIONS Show tree entries even when going to recurse them. Has no effect if '-r' was not passed. '-d' implies '-t'. +-l:: +--long:: + Show object size of blob (file) entries. + -z:: \0 line termination on output. @@ -65,6 +69,14 @@ Output Format When the `-z` option is not used, TAB, LF, and backslash characters in pathnames are represented as `\t`, `\n`, and `\\`, respectively. +When the `-l` option is used, format changes to + + <mode> SP <type> SP <object> SP <object size> TAB <file> + +Object size identified by <object> is given in bytes, and right-justified +with minimum width of 7 characters. Object size is given only for blobs +(file) entries; for other entries `-` character is used in place of size. + Author ------ @@ -80,4 +92,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 8eadcebfcf..64aa6a1ea6 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -16,7 +16,7 @@ DESCRIPTION Reading a single e-mail message from the standard input, and writes the commit log message in <msg> file, and the patches in <patch> file. The author name, e-mail and e-mail subject are -written out to the standard output to be used by git-applypatch +written out to the standard output to be used by git-am to create a commit. It is usually not necessary to use this command directly. See gitlink:git-am[1] instead. @@ -67,4 +67,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index c11d6a530f..c4f4cabbdc 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -7,12 +7,15 @@ git-mailsplit - Simple UNIX mbox splitter program SYNOPSIS -------- -'git-mailsplit' [-b] [-f<nn>] [-d<prec>] -o<directory> [--] [<mbox>...] +'git-mailsplit' [-b] [-f<nn>] [-d<prec>] -o<directory> [--] [<mbox>|<Maildir>...] DESCRIPTION ----------- -Splits a mbox file into a list of files: "0001" "0002" .. in the specified -directory so you can process them further from there. +Splits a mbox file or a Maildir into a list of files: "0001" "0002" .. in the +specified directory so you can process them further from there. + +IMPORTANT: Maildir splitting relies upon filenames being sorted to output +patches in the correct order. OPTIONS ------- @@ -20,6 +23,10 @@ OPTIONS Mbox file to split. If not given, the mbox is read from the standard input. +<Maildir>:: + Root of the Maildir to split. This directory should contain the cur, tmp + and new subdirectories. + <directory>:: Directory in which to place the individual messages. @@ -49,4 +56,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 3190aed108..6b71880ec4 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -40,4 +40,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index b8ee1ff2b0..17e9f10c65 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -59,7 +59,7 @@ Examples: This is modified MM in the branch B. # merge2 This is modified MM in the branch B. # current contents -or +or torvalds@ppc970:~/merge-test> git-merge-index cat AA MM cat: : No such file or directory @@ -85,4 +85,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.txt index f80ab3b8c4..f35d0e1b45 100644 --- a/Documentation/git-merge-one-file.txt +++ b/Documentation/git-merge-one-file.txt @@ -27,4 +27,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index 35fb4fb713..6892fdac3d 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -34,4 +34,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 9c08efa53a..144bc16ff2 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] [--no-commit] [--squash] [-s <strategy>]... +'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]... [-m <msg>] <remote> <remote>... DESCRIPTION @@ -43,6 +43,21 @@ If you tried a merge which resulted in a complex conflicts and would want to start over, you can recover with gitlink: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 overriden by 'GIT_MERGE_VERBOSITY' environment variable. + HOW MERGE WORKS --------------- @@ -92,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-mergetool.txt b/Documentation/git-mergetool.txt index add01e855a..6c32c6d18e 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -25,7 +25,7 @@ OPTIONS -t or --tool=<tool>:: Use the merge resolution program specified by <tool>. Valid merge tools are: - kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, and opendiff + kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, and opendiff + If a merge resolution program is not specified, 'git mergetool' will use the configuration variable merge.tool. If the @@ -43,4 +43,3 @@ Documentation by Theodore Y Ts'o. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 2860a3d1ba..ea7a75234a 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -19,18 +19,18 @@ The output is the new tag's <object> identifier. Tag Format ---------- -A tag signature file has a very simple fixed format: three lines of +A tag signature file has a very simple fixed format: four lines of object <sha1> type <typename> tag <tagname> + tagger <tagger> -followed by some 'optional' free-form signature that git itself -doesn't care about, but that can be verified with gpg or similar. - -The size of the full object is artificially limited to 8kB. (Just -because I'm a lazy bastard, and if you can't fit a signature in that -size, you're doing something wrong) +followed by some 'optional' free-form message (some tags created +by older git may not have `tagger` line). The message, when +exists, is separated by a blank line from the header. The +message part may contain a signature that git itself doesn't +care about, but that can be verified with gpg. Author @@ -44,4 +44,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index 5f9ee603b7..638abc7d0f 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -32,4 +32,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index 6756b76bb1..2c9cf743c7 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -51,4 +51,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index d6c8bf800f..306e1a4956 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -34,6 +34,13 @@ OPTIONS Read from stdin, append "(<rev_name>)" to all sha1's of nameable commits, and pass to stdout +--name-only:: + Instead of printing both the SHA-1 and the name, print only + the name. If given with --tags the usual tag prefix of + "tags/" is also omitted from the name, matching the output + of gitlink::git-describe[1] more closely. This option + cannot be combined with --stdin. + EXAMPLE ------- @@ -69,4 +76,3 @@ Documentation by Johannes Schindelin. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-p4import.txt b/Documentation/git-p4import.txt deleted file mode 100644 index 714abbe28e..0000000000 --- a/Documentation/git-p4import.txt +++ /dev/null @@ -1,168 +0,0 @@ -git-p4import(1) -=============== - -NAME ----- -git-p4import - Import a Perforce repository into git - - -SYNOPSIS --------- -[verse] -`git-p4import` [-q|-v] [--notags] [--authors <file>] [-t <timezone>] - <//p4repo/path> <branch> -`git-p4import` --stitch <//p4repo/path> -`git-p4import` - - -DESCRIPTION ------------ -Import a Perforce repository into an existing git repository. When -a <//p4repo/path> and <branch> are specified a new branch with the -given name will be created and the initial import will begin. - -Once the initial import is complete you can do an incremental import -of new commits from the Perforce repository. You do this by checking -out the appropriate git branch and then running `git-p4import` without -any options. - -The standard p4 client is used to communicate with the Perforce -repository; it must be configured correctly in order for `git-p4import` -to operate (see below). - - -OPTIONS -------- --q:: - Do not display any progress information. - --v:: - Give extra progress information. - -\--authors:: - Specify an authors file containing a mapping of Perforce user - ids to full names and email addresses (see Notes below). - -\--notags:: - Do not create a tag for each imported commit. - -\--stitch:: - Import the contents of the given perforce branch into the - currently checked out git branch. - -\--log:: - Store debugging information in the specified file. - --t:: - Specify that the remote repository is in the specified timezone. - Timezone must be in the format "US/Pacific" or "Europe/London" - etc. You only need to specify this once, it will be saved in - the git config file for the repository. - -<//p4repo/path>:: - The Perforce path that will be imported into the specified branch. - -<branch>:: - The new branch that will be created to hold the Perforce imports. - - -P4 Client ---------- -You must make the `p4` client command available in your $PATH and -configure it to communicate with the target Perforce repository. -Typically this means you must set the "$P4PORT" and "$P4CLIENT" -environment variables. - -You must also configure a `p4` client "view" which maps the Perforce -branch into the top level of your git repository, for example: - ------------- -Client: myhost - -Root: /home/sean/import - -Options: noallwrite clobber nocompress unlocked modtime rmdir - -View: - //public/jam/... //myhost/jam/... ------------- - -With the above `p4` client setup, you could import the "jam" -perforce branch into a branch named "jammy", like so: - ------------- -$ mkdir -p /home/sean/import/jam -$ cd /home/sean/import/jam -$ git init -$ git p4import //public/jam jammy ------------- - - -Multiple Branches ------------------ -Note that by creating multiple "views" you can use `git-p4import` -to import additional branches into the same git repository. -However, the `p4` client has a limitation in that it silently -ignores all but the last "view" that maps into the same local -directory. So the following will *not* work: - ------------- -View: - //public/jam/... //myhost/jam/... - //public/other/... //myhost/jam/... - //public/guest/... //myhost/jam/... ------------- - -If you want more than one Perforce branch to be imported into the -same directory you must employ a workaround. A simple option is -to adjust your `p4` client before each import to only include a -single view. - -Another option is to create multiple symlinks locally which all -point to the same directory in your git repository and then use -one per "view" instead of listing the actual directory. - - -Tags ----- -A git tag of the form p4/xx is created for every change imported from -the Perforce repository where xx is the Perforce changeset number. -Therefore after the import you can use git to access any commit by its -Perforce number, e.g. git show p4/327. - -The tag associated with the HEAD commit is also how `git-p4import` -determines if there are new changes to incrementally import from the -Perforce repository. - -If you import from a repository with many thousands of changes -you will have an equal number of p4/xxxx git tags. Git tags can -be expensive in terms of disk space and repository operations. -If you don't need to perform further incremental imports, you -may delete the tags. - - -Notes ------ -You can interrupt the import (e.g. ctrl-c) at any time and restart it -without worry. - -Author information is automatically determined by querying the -Perforce "users" table using the id associated with each change. -However, if you want to manually supply these mappings you can do -so with the "--authors" option. It accepts a file containing a list -of mappings with each line containing one mapping in the format: - ------------- - perforce_id = Full Name <email@address.com> ------------- - - -Author ------- -Written by Sean Estabrooks <seanlkml@sympatico.ca> - - -GIT ---- -Part of the gitlink:git[7] suite - diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index bd3ee456e3..6f17cff24a 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -85,6 +85,22 @@ base-name:: times to get to the necessary object. The default value for --window is 10 and --depth is 50. +--window-memory=[N]:: + This option provides an additional limit on top of `--window`; + the window size will dynamically scale down so as to not take + up more than N bytes in memory. This is useful in + repositories with a mix of large and small objects to not run + out of memory with a large window, but still be able to take + advantage of the large window for the smaller objects. The + size can be suffixed with "k", "m", or "g". + `--window-memory=0` makes memory usage unlimited, which is the + default. + +--max-pack-size=<n>:: + Maximum size of each output packfile, expressed in MiB. + If specified, multiple packfiles may be created. + The default is unlimited. + --incremental:: This flag causes an object already in a pack ignored even if it appears in the standard input. @@ -127,6 +143,25 @@ base-name:: This flag tells the command not to reuse existing deltas but compute them from scratch. +--no-reuse-object:: + This flag tells the command not to reuse existing object data at all, + including non deltified object, forcing recompression of everything. + This implies --no-reuse-delta. Useful only in the obscure case where + wholesale enforcement of a different compression level on the + packed data is desired. + +--compression=[N]:: + Specifies compression level for newly-compressed data in the + generated pack. If not specified, pack compression level is + determined first by pack.compression, then by core.compression, + and defaults to -1, the zlib default, if neither is set. + Data copied from loose objects will be recompressed + if core.legacyheaders was true when they were created or if + the loose compression level (see core.loosecompression and + core.compression) is now a different value than the pack + compression level. Add --no-reuse-object if you want to force + a uniform compression level on all data no matter the source. + --delta-base-offset:: A packed archive can express base object of a delta as either 20-byte object name or as an offset in the @@ -161,4 +196,3 @@ gitlink:git-prune-packed[1] GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index 94bbea0db2..f2ceebac4b 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -17,7 +17,7 @@ are redundant. The output is suitable for piping to 'xargs rm' if you are in the root of the repository. git-pack-redundant accepts a list of objects on standard input. Any objects -given will be ignored when checking which packs are required. This makes the +given will be ignored when checking which packs are required. This makes the following command useful when wanting to remove packs which contain unreachable objects. @@ -55,4 +55,3 @@ gitlink:git-prune-packed[1] GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index a7e9fd021a..ad528a9224 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -40,4 +40,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt index 74f37bd904..abc171266a 100644 --- a/Documentation/git-peek-remote.txt +++ b/Documentation/git-peek-remote.txt @@ -52,4 +52,3 @@ Documentation by Junio C Hamano. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 310033e460..3800edb7bb 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -50,4 +50,3 @@ gitlink:git-repack[1] GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index b8166a210f..0ace233d18 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -58,4 +58,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 94478ed94d..e1eb2c1d00 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -29,7 +29,7 @@ include::fetch-options.txt[] include::pull-fetch-param.txt[] -include::urls.txt[] +include::urls-remotes.txt[] include::merge-strategies.txt[] @@ -165,4 +165,3 @@ Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index e9ad10672a..0dd9caf867 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -53,9 +53,8 @@ side are updated. + `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. + -A parameter <ref> without a colon is equivalent to -<ref>`:`<ref>, hence updates <ref> in the destination from <ref> -in the source. +A parameter <ref> without a colon pushes the <ref> from the source +repository to the destination repository under the same name. + Pushing an empty <src> allows you to delete the <dst> ref from the remote repository. @@ -80,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. @@ -96,7 +95,27 @@ the remote repository. -v:: Run verbosely. -include::urls.txt[] +include::urls-remotes.txt[] + + +Examples +-------- + +git push origin master:: + Find a ref that matches `master` in the source repository + (most likely, it would find `refs/heads/master`), and update + the same ref (e.g. `refs/heads/master`) in `origin` repository + with it. + +git push origin :experimental:: + Find a ref that matches `experimental` in the `origin` repository + (e.g. `refs/heads/experimental`), and delete it. + +git push origin master:satellite/master:: + Find a ref that matches `master` in the source repository + (most likely, it would find `refs/heads/master`), and update + the ref that matches `satellite/master` (most likely, it would + be `refs/remotes/satellite/master`) in `origin` repository with it. Author ------ @@ -110,4 +129,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index 296937a416..1c3ef4c593 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -58,4 +58,3 @@ Documentation by Eric Biederman <ebiederm@lnxi.com> GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index acb57447a8..74c5478ba1 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,7 +8,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- -'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) +'git-read-tree' (<tree-ish> | [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) DESCRIPTION @@ -50,6 +50,12 @@ OPTIONS trees that are not directly related to the current working tree status into a temporary index file. +--trivial:: + Restrict three-way merge by `git-read-tree` to happen + only if there is no file-level merging required, instead + of resolving merge for trivial cases and leaving + conflicting files unresolved in the index. + --aggressive:: Usually a three-way merge by `git-read-tree` resolves the merge for really trivial cases and leaves other @@ -356,4 +362,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 753b275a0f..a1b6dce73d 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -8,7 +8,8 @@ git-rebase - Forward-port local commits to the updated upstream head SYNOPSIS -------- [verse] -'git-rebase' [-v] [--merge] [-C<n>] [--onto <newbase>] <upstream> [<branch>] +'git-rebase' [-i | --interactive] [-v | --verbose] [--merge] [-C<n>] + [-p | --preserve-merges] [--onto <newbase>] <upstream> [<branch>] 'git-rebase' --continue | --skip | --abort DESCRIPTION @@ -129,7 +130,7 @@ the following situation: then the command - git-rebase --onto topicA~5 topicA~2 topicA + git-rebase --onto topicA~5 topicA~3 topicA would result in the removal of commits F and G: @@ -208,6 +209,14 @@ OPTIONS context exist they all must match. By default no context is ever ignored. +-i, \--interactive:: + Make a list of the commits which are about to be rebased. Let the + user edit that list before rebasing. + +-p, \--preserve-merges:: + Instead of ignoring merges, try to recreate them. This option + only works in interactive mode. + include::merge-strategies.txt[] NOTES @@ -226,9 +235,100 @@ pre-rebase hook script for an example. You must be in the top directory of your project to start (or continue) a rebase. Upon completion, <branch> will be the current branch. -Author +INTERACTIVE MODE +---------------- + +Rebasing interactively means that you have a chance to edit the commits +which are rebased. You can reorder the commits, and you can +remove them (weeding out bad or otherwise unwanted patches). + +The interactive mode is meant for this type of workflow: + +1. have a wonderful idea +2. hack on the code +3. prepare a series for submission +4. submit + +where point 2. consists of several instances of + +a. regular use + 1. finish something worthy of a commit + 2. commit +b. independent fixup + 1. realize that something does not work + 2. fix that + 3. commit it + +Sometimes the thing fixed in b.2. cannot be amended to the not-quite +perfect commit it fixes, because that commit is buried deeply in a +patch series. That is exactly what interactive rebase is for: use it +after plenty of "a"s and "b"s, by rearranging and editing +commits, and squashing multiple commits into one. + +Start it with the last commit you want to retain as-is: + + git rebase -i <after-this-commit> + +An editor will be fired up with all the commits in your current branch +(ignoring merge commits), which come after the given commit. You can +reorder the commits in this list to your heart's content, and you can +remove them. The list looks more or less like this: + +------------------------------------------- +pick deadbee The oneline of this commit +pick fa1afe1 The oneline of the next commit +... +------------------------------------------- + +The oneline descriptions are purely for your pleasure; `git-rebase` will +not look at them but at the commit names ("deadbee" and "fa1afe1" in this +example), so do not delete or edit the names. + +By replacing the command "pick" with the command "edit", you can tell +`git-rebase` to stop after applying that commit, so that you can edit +the files and/or the commit message, amend the commit, and continue +rebasing. + +If you want to fold two or more commits into one, replace the command +"pick" with "squash" for the second and subsequent commit. If the +commits had different authors, it will attribute the squashed commit to +the author of the last commit. + +In both cases, or when a "pick" does not succeed (because of merge +errors), the loop will stop to let you fix things, and you can continue +the loop with `git rebase --continue`. + +For example, if you want to reorder the last 5 commits, such that what +was HEAD~4 becomes the new HEAD. To achieve that, you would call +`git-rebase` like this: + +---------------------- +$ git rebase -i HEAD~5 +---------------------- + +And move the first patch to the end of the list. + +You might want to preserve merges, if you have a history like this: + +------------------ + X + \ + A---M---B + / +---o---O---P---Q +------------------ + +Suppose you want to rebase the side branch starting at "A" to "Q". Make +sure that the current HEAD is "B", and call + +----------------------------- +$ git rebase -i -p --onto Q O +----------------------------- + +Authors ------ -Written by Junio C Hamano <junkio@cox.net> +Written by Junio C Hamano <junkio@cox.net> and +Johannes E. Schindelin <johannes.schindelin@gmx.de> Documentation -------------- @@ -237,4 +337,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 6914aa59c3..2633d94c59 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -48,8 +48,8 @@ standard input of the hook will be one line per ref to be updated: The refname value is relative to $GIT_DIR; e.g. for the master head this is "refs/heads/master". The two sha1 values before each refname are the object names for the refname before and after -the update. Refs to be created will have sha1-old equal to 0{40}, -while refs to be deleted will have sha1-new equal to 0{40}, otherwise +the update. Refs to be created will have sha1-old equal to 0\{40}, +while refs to be deleted will have sha1-new equal to 0\{40}, otherwise sha1-old and sha1-new should be valid objects in the repository. This hook is called before any refname is updated and before any @@ -71,14 +71,14 @@ The refname parameter is relative to $GIT_DIR; e.g. for the master head this is "refs/heads/master". The two sha1 arguments are the object names for the refname before and after the update. Note that the hook is called before the refname is updated, -so either sha1-old is 0{40} (meaning there is no such ref yet), +so either sha1-old is 0\{40} (meaning there is no such ref yet), or it should match what is recorded in refname. The hook should exit with non-zero status if it wants to disallow updating the named ref. Otherwise it should exit with zero. Successful execution (a zero exit status) of this hook does not -ensure the ref will actully be updated, it is only a prerequisite. +ensure the ref will actually be updated, it is only a prerequisite. As such it is not a good idea to send notices (e.g. email) from this hook. Consider using the post-receive hook instead. @@ -96,8 +96,8 @@ The refname value is relative to $GIT_DIR; e.g. for the master head this is "refs/heads/master". The two sha1 values before each refname are the object names for the refname before and after the update. Refs that were created will have sha1-old equal to -0{40}, while refs that were deleted will have sha1-new equal to -0{40}, otherwise sha1-old and sha1-new should be valid objects in +0\{40}, while refs that were deleted will have sha1-new equal to +0\{40}, otherwise sha1-old and sha1-new should be valid objects in the repository. Using this hook, it is easy to generate mails describing the updates diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 1e343bcdcd..5180f6810d 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -30,15 +30,29 @@ Entries older than `expire` time, or entries older than tip, are removed from the reflog. This is typically not used directly by the end users -- instead, see gitlink:git-gc[1]. -The subcommand "show" (which is also the default, in the absense of any +The subcommand "show" (which is also the default, in the absence of any subcommands) will take all the normal log options, and show the log of -the current branch. It is basically an alias for 'git log -g --abbrev-commit +`HEAD`, which will cover all recent actions, including branch switches. +It is basically an alias for 'git log -g --abbrev-commit --pretty=oneline', see gitlink:git-log[1]. OPTIONS ------- +--stale-fix:: + This revamps the logic -- the definition of "broken commit" + becomes: a commit that is not reachable from any of the refs and + there is a missing object among the commit, tree, or blob + objects reachable from it that is not reachable from any of the + refs. ++ +This computation involves traversing all the reachable objects, i.e. it +has the same cost as 'git prune'. Fortunately, once this is run, we +should not have to ever worry about missing objects, because the current +prune and pack-objects know about reflogs and protect objects referred by +them. + --expire=<time>:: Entries older than this time are pruned. Without the option it is taken from configuration `gc.reflogExpire`, @@ -65,4 +79,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt index aca60120c8..fe631bb3dd 100644 --- a/Documentation/git-relink.txt +++ b/Documentation/git-relink.txt @@ -34,4 +34,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index b35c65ba3b..61a6022ce8 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -135,4 +135,3 @@ Documentation by J. Bruce Fields and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index c57013b953..12e2079a7c 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -14,7 +14,7 @@ DESCRIPTION ----------- This script is used to combine all objects that do not currently -reside in a "pack", into a pack. It can also be used to re-organise +reside in a "pack", into a pack. It can also be used to re-organize existing packs into a single, more efficient pack. A pack is a collection of objects, individually compressed, with @@ -68,6 +68,22 @@ OPTIONS to be applied that many times to get to the necessary object. The default value for --window is 10 and --depth is 50. +--window-memory=[N]:: + This option provides an additional limit on top of `--window`; + the window size will dynamically scale down so as to not take + up more than N bytes in memory. This is useful in + repositories with a mix of large and small objects to not run + out of memory with a large window, but still be able to take + advantage of the large window for the smaller objects. The + size can be suffixed with "k", "m", or "g". + `--window-memory=0` makes memory usage unlimited, which is the + default. + +--max-pack-size=<n>:: + Maximum size of each output packfile, expressed in MiB. + If specified, multiple packfiles may be created. + The default is unlimited. + Configuration ------------- @@ -99,4 +115,3 @@ gitlink:git-prune-packed[1] GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 478a5fd6b7..087eeb7cc2 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -37,4 +37,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 7ff9b05e68..c4d4263238 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -23,7 +23,7 @@ initial manual merge, and later by noticing the same automerge results and applying the previously recorded hand resolution. [NOTE] -You need to create `$GIT_DIR/rr-cache` directory to enable this +You need to set the config variable rerere.enabled to enable this command. @@ -171,7 +171,7 @@ records it if it is a new conflict, or reuses the earlier hand resolve when it is not. `git-commit` also invokes `git-rerere` when recording a merge result. What this means is that you do not have to do anything special yourself (Note: you still have -to create `$GIT_DIR/rr-cache` directory to enable this command). +to set the config variable rerere.enabled to enable this command). In our example, when you did the test merge, the manual resolution is recorded, and it will be reused when you do the 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 c3c2043d18..7cd0e8913e 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -16,16 +16,20 @@ SYNOPSIS [ \--sparse ] [ \--no-merges ] [ \--remove-empty ] + [ \--full-history ] [ \--not ] [ \--all ] [ \--stdin ] [ \--topo-order ] [ \--parents ] + [ \--timestamp ] [ \--left-right ] [ \--cherry-pick ] [ \--encoding[=<encoding>] ] [ \--(author|committer|grep)=<pattern> ] - [ \--date={local|relative|default} ] + [ \--regexp-ignore-case | \-i ] + [ \--extended-regexp | \-E ] + [ \--date={local|relative|default|iso|rfc|short} ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] [ \--bisect ] @@ -33,6 +37,7 @@ SYNOPSIS [ \--merge ] [ \--reverse ] [ \--walk-reflogs ] + [ \--no-walk ] [ \--do-walk ] <commit>... [ \-- <paths>... ] DESCRIPTION @@ -93,7 +98,7 @@ include::pretty-options.txt[] Synonym for `--date=relative`. ---date={relative,local,default}:: +--date={relative,local,default,iso,rfc}:: Only takes effect for dates shown in human-readable format, such as when using "--pretty". @@ -103,6 +108,13 @@ e.g. "2 hours ago". + `--date=local` shows timestamps in user's local timezone. + +`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format. ++ +`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 +format, often found in E-mail messages. ++ +`--date=short` shows only date but not time, in `YYYY-MM-DD` format. ++ `--date=default` shows timestamps in the original timezone (either committer's or author's). @@ -115,6 +127,9 @@ e.g. "2 hours ago". Print the parents of the commit. +--timestamp:: + Print the raw commit timestamp. + --left-right:: Mark which side of a symmetric diff a commit is reachable from. @@ -214,10 +229,27 @@ limiting may be applied. Limit the commits output to ones with log message that matches the specified pattern (regular expression). +-i, --regexp-ignore-case:: + + Match the regexp limiting patterns without regard to letters case. + +-E, --extended-regexp:: + + Consider the limiting patterns to be extended regular expressions + instead of the default basic regular expressions. + --remove-empty:: Stop when a given path disappears from the tree. +--full-history:: + + Show also parts of history irrelevant to current state of a given + path. This turns off history simplification, which removed merges + which didn't change anything at all at some child. It will still actually + simplify away merges that didn't change anything at all into either + child. + --no-merges:: Do not print commits with more than one parent. @@ -261,12 +293,14 @@ excluded from the output. + With '\--pretty' format other than oneline (for obvious reasons), this causes the output to have two extra lines of information -taken from the reflog. By default, 'commit@{Nth}' notation is +taken from the reflog. By default, 'commit@\{Nth}' notation is used in the output. When the starting commit is specified as -'commit@{now}', output also uses 'commit@{timestamp}' notation +'commit@{now}', output also uses 'commit@\{timestamp}' notation instead. Under '\--pretty=oneline', the commit message is prefixed with this information on the same line. +Cannot be combined with '\--reverse'. + --merge:: After a failed merge, show refs that touch files having a @@ -341,6 +375,7 @@ By default, the commits are shown in reverse chronological order. --reverse:: Output the commits in reverse order. + Cannot be combined with '\--walk-reflogs'. Object Traversal ~~~~~~~~~~~~~~~~ @@ -367,6 +402,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 7757abe621..4758c33dee 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -89,6 +89,17 @@ OPTIONS --git-dir:: Show `$GIT_DIR` if defined else show the path to the .git directory. +--is-inside-git-dir:: + When the current working directory is below the repository + directory print "true", otherwise "false". + +--is-inside-work-tree:: + When the current working directory is inside the work tree of the + repository print "true", otherwise "false". + +--is-bare-repository:: + When the repository is bare print "true", otherwise "false". + --short, --short=number:: Instead of outputting the full SHA1 values of object names try to abbreviate them to a shorter unique name. When no length is specified @@ -204,7 +215,10 @@ blobs contained in a commit. * A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path; this names a blob object in the index at the given path. Missing stage number (and the colon - that follows it) names an stage 0 entry. + that follows it) names an stage 0 entry. During a merge, stage + 1 is the common ancestor, stage 2 is the target branch's version + (typically the current branch), and stage 3 is the version from + the branch being merged. Here is an illustration, by Jon Loeliger. Both node B and C are a commit parents of commit node A. Parent commits are ordered @@ -213,7 +227,7 @@ left-to-right. G H I J \ / \ / D E F - \ | / \ + \ | / \ \ | / | \|/ | B C @@ -286,4 +300,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 8081bbaffa..69db498447 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -56,4 +56,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index a65f24a0f6..be61a82164 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -14,7 +14,8 @@ DESCRIPTION Remove files from the working tree and from the index. The files have to be identical to the tip of the branch, and no updates to its contents must have been placed in the staging -area (aka index). +area (aka index). When --cached is given, the staged content has to +match either the tip of the branch *or* the file on disk. OPTIONS @@ -95,4 +96,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-runstatus.txt b/Documentation/git-runstatus.txt index 8bb52f4687..dee5d0da9d 100644 --- a/Documentation/git-runstatus.txt +++ b/Documentation/git-runstatus.txt @@ -66,4 +66,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 7ae39fd5a2..8231286e09 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -44,8 +44,8 @@ The --cc option must be repeated for each user you want on the cc list. value; if that is unspecified, default to --chain-reply-to. --compose:: - Use $EDITOR to edit an introductory message for the - patch series. + Use $GIT_EDITOR, core.editor, $VISUAL, or $EDITOR to edit an + introductory message for the patch series. --from:: Specify the sender of the emails. This will default to @@ -59,9 +59,11 @@ The --cc option must be repeated for each user you want on the cc list. Only necessary if --compose is also set. If --compose is not set, this will be prompted for. ---no-signed-off-by-cc:: - Do not add emails found in Signed-off-by: or Cc: lines to the - cc list. +--signed-off-by-cc, --no-signed-off-by-cc:: + If this is set, add emails found in Signed-off-by: or Cc: lines to the + cc list. + Default is the value of 'sendemail.signedoffcc' configuration value; + if that is unspecified, default to --signed-off-by-cc. --quiet:: Make git-send-email less verbose. One line per email should be @@ -78,13 +80,22 @@ The --cc option must be repeated for each user you want on the cc list. `localhost` otherwise. --subject:: - Specify the initial subject of the email thread. + Specify the initial subject of the email thread. Only necessary if --compose is also set. If --compose is not set, this will be prompted for. ---suppress-from:: - Do not add the From: address to the cc: list, if it shows up in a From: - line. +--suppress-from, --no-suppress-from:: + If this is set, do not add the From: address to the cc: list, if it + shows up in a From: line. + Default is the value of 'sendemail.suppressfrom' configuration value; + if that is unspecified, default to --no-suppress-from. + +--thread, --no-thread:: + If this is set, the In-Reply-To header will be set on each email sent. + If disabled with "--no-thread", no emails will have the In-Reply-To + header set. + Default is the value of the 'sendemail.thread' configuration value; + if that is unspecified, default to --thread. --dry-run:: Do everything except actually send the emails. @@ -137,4 +148,3 @@ Documentation by Ryan Anderson GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 2b2abebd60..1ea1faa1b5 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -69,4 +69,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index 228b9f14f3..48f2d57b7b 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -32,4 +32,3 @@ Documentation by Petr Baudis and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 15cc6f77c1..2220ef6ea8 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -56,4 +56,3 @@ Documentation by Junio C Hamano. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index be09b62beb..764d99356b 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -32,4 +32,3 @@ Documentation by Junio C Hamano GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 34c5caf2d0..a42e121150 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -84,4 +84,3 @@ This manual page is a stub. You can help the git documentation by expanding it. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-ssh-fetch.txt b/Documentation/git-ssh-fetch.txt index 192b1f15a9..8d3e2ffb2c 100644 --- a/Documentation/git-ssh-fetch.txt +++ b/Documentation/git-ssh-fetch.txt @@ -13,6 +13,8 @@ SYNOPSIS DESCRIPTION ----------- +THIS COMMAND IS DEPRECATED. + Pulls from a remote repository over ssh connection, invoking git-ssh-upload on the other end. It functions identically to git-ssh-upload, aside from which end you run it on. @@ -48,4 +50,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-ssh-upload.txt b/Documentation/git-ssh-upload.txt index a9b7e9f974..5e2ca8dccf 100644 --- a/Documentation/git-ssh-upload.txt +++ b/Documentation/git-ssh-upload.txt @@ -12,6 +12,8 @@ SYNOPSIS DESCRIPTION ----------- +THIS COMMAND IS DEPRECATED. + Pushes from a remote repository over ssh connection, invoking git-ssh-fetch on the other end. It functions identically to git-ssh-fetch, aside from which end you run it on. @@ -44,4 +46,3 @@ Documentation by Daniel Barkalow GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt new file mode 100644 index 0000000000..05f40cff6c --- /dev/null +++ b/Documentation/git-stash.txt @@ -0,0 +1,165 @@ +git-stash(1) +============ + +NAME +---- +git-stash - Stash the changes in a dirty working directory away + +SYNOPSIS +-------- +[verse] +'git-stash' (list | show [<stash>] | apply [<stash>] | clear) +'git-stash' [save] [message...] + +DESCRIPTION +----------- + +Use 'git-stash' when you want to record the current state of the +working directory and the index, but want to go back to a clean +working directory. The command saves your local modifications away +and reverts the working directory to match the `HEAD` commit. + +The modifications stashed away by this command can be listed with +`git-stash list`, inspected with `git-stash show`, and restored +(potentially on top of a different commit) with `git-stash apply`. +Calling git-stash without any arguments is equivalent to `git-stash +save`. A stash is by default listed as "WIP on 'branchname' ...", but +you can give a more descriptive message on the command line when +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@\{0}` is the most recently +created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}` +is also possible). + +OPTIONS +------- + +save:: + + Save your local modifications to a new 'stash', and run `git-reset + --hard` to revert them. This is the default action when no + subcommand is given. + +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 + 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. ++ +---------------------------------------------------------------- +stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation +stash@{1}: On master: 9cc0589... Add git-stash +---------------------------------------------------------------- + +show [<stash>]:: + + Show the changes recorded in the stash as a diff between the the + 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@\{1}` to view the second most recent stash in patch form). + +apply [<stash>]:: + + Restore the changes recorded in the stash on top of the current + working tree state. When no `<stash>` is given, applies the latest + one. The working directory must match the index. ++ +This operation can fail with conflicts; you need to resolve them +by hand in the working tree. + +clear:: + Remove all the stashed states. Note that those states will then + be subject to pruning, and may be difficult or impossible to recover. + + +DISCUSSION +---------- + +A stash is represented as a commit whose tree records the state of the +working directory, and its first parent is the commit at `HEAD` when +the stash was created. The tree of the second parent records the +state of the index when the stash is made, and it is made a child of +the `HEAD` commit. The ancestry graph looks like this: + + .----W + / / + -----H----I + +where `H` is the `HEAD` commit, `I` is a commit that records the state +of the index, and `W` is a commit that records the state of the working +tree. + + +EXAMPLES +-------- + +Pulling into a dirty tree:: + +When you are in the middle of something, you learn that there are +upstream changes that are possibly relevant to what you are +doing. When your local changes do not conflict with the changes in +the upstream, a simple `git pull` will let you move forward. ++ +However, there are cases in which your local changes do conflict with +the upstream changes, and `git pull` refuses to overwrite your +changes. In such a case, you can stash your changes away, +perform a pull, and then unstash, like this: ++ +---------------------------------------------------------------- +$ git pull +... +file foobar not up to date, cannot merge. +$ git stash +$ git pull +$ git stash apply +---------------------------------------------------------------- + +Interrupted workflow:: + +When you are in the middle of something, your boss comes in and +demands that you fix something immediately. Traditionally, you would +make a commit to a temporary branch to store your changes away, and +return to your original branch to make the emergency fix, like this: ++ +---------------------------------------------------------------- +... hack hack hack ... +$ git checkout -b my_wip +$ git commit -a -m "WIP" +$ git checkout master +$ edit emergency fix +$ git commit -a -m "Fix in a hurry" +$ git checkout my_wip +$ git reset --soft HEAD^ +... continue hacking ... +---------------------------------------------------------------- ++ +You can use `git-stash` to simplify the above, like this: ++ +---------------------------------------------------------------- +... hack hack hack ... +$ git stash +$ edit emergency fix +$ git commit -a -m "Fix in a hurry" +$ git stash apply +... continue hacking ... +---------------------------------------------------------------- + +SEE ALSO +-------- +gitlink:git-checkout[1], +gitlink:git-commit[1], +gitlink:git-reflog[1], +gitlink:git-reset[1] + +AUTHOR +------ +Written by Nanako Shiraishi <nanako3@bluebottle.com> + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 1fd1af102a..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 ------ @@ -58,4 +65,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index 3a03dd0410..5212358306 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -8,7 +8,7 @@ git-stripspace - Filter out empty lines SYNOPSIS -------- -'git-stripspace' < <stream> +'git-stripspace' [-s | --strip-comments] < <stream> DESCRIPTION ----------- @@ -16,6 +16,9 @@ Remove multiple empty lines, and empty lines at beginning and end. OPTIONS ------- +-s\|--strip-comments:: + In addition to empty lines, also strip lines starting with '#'. + <stream>:: Byte stream to act on. @@ -30,4 +33,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt new file mode 100644 index 0000000000..2c48936fcd --- /dev/null +++ b/Documentation/git-submodule.txt @@ -0,0 +1,77 @@ +git-submodule(1) +================ + +NAME +---- +git-submodule - Initialize, update or inspect submodules + + +SYNOPSIS +-------- +[verse] +'git-submodule' [--quiet] [-b branch] add <repository> [<path>] +'git-submodule' [--quiet] [--cached] [status|init|update] [--] [<path>...] + + +COMMANDS +-------- +add:: + Add the given repository as a submodule at the given path + to the changeset to be committed next. In particular, the + repository is cloned at the specified path, added to the + changeset and registered in .gitmodules. If no path is + specified, the path is deduced from the repository specification. + +status:: + Show the status of the submodules. This will print the SHA-1 of the + currently checked out commit for each submodule, along with the + submodule path and the output of gitlink:git-describe[1] for the + SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not + initialized and `+` if the currently checked out submodule commit + does not match the SHA-1 found in the index of the containing + repository. This command is the default command for git-submodule. + +init:: + Initialize the submodules, i.e. register in .git/config each submodule + name and url found in .gitmodules. The key used in .git/config is + `submodule.$name.url`. This command does not alter existing information + in .git/config. + +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. + + +OPTIONS +------- +-q, --quiet:: + Only print error messages. + +-b, --branch:: + Branch of repository to add as submodule. + +--cached:: + Display the SHA-1 stored in the index, not the SHA-1 of the currently + checked out submodule commit. This option is only valid for the + status command. + +<path>:: + Path to submodule(s). When specified this will restrict the command + to only operate on the submodules found at the specified paths. + +FILES +----- +When initializing submodules, a .gitmodules file in the top-level directory +of the containing repository is used to find the url of each submodule. +This file should be formatted in the same way as $GIR_DIR/config. The key +to each submodule url is "submodule.$name.url". + + +AUTHOR +------ +Written by Lars Hjemli <hjemli@gmail.com> + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index c0d7d9597b..3420c5c958 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -44,10 +44,15 @@ COMMANDS --tags=<tags_subdir>;; -b<branches_subdir>;; --branches=<branches_subdir>;; +-s;; +--stdlayout;; These are optional command-line options for init. Each of these flags can point to a relative repository path (--tags=project/tags') or a full url - (--tags=https://foo.org/project/tags) + (--tags=https://foo.org/project/tags). The option --stdlayout is + a shorthand way of setting trunk,tags,branches as the relative paths, + which is the Subversion default. If any of the other options are given + as well, they take precedence. --no-metadata;; Set the 'noMetadata' option in the [svn-remote] config. --use-svm-props;; @@ -66,9 +71,10 @@ COMMANDS to the names of remotes if trunk/branches/tags are specified. The prefix does not automatically include a trailing slash, so be sure you include one in the - argument if that is what you want. This is useful if - you wish to track multiple projects that share a common - repository. + argument if that is what you want. If --branches/-b is + specified, the prefix must include a trailing slash. + Setting a prefix is useful if you wish to track multiple + projects that share a common repository. 'fetch':: Fetch unfetched revisions from the Subversion remote we are @@ -93,7 +99,7 @@ COMMANDS This works similarly to 'svn update' or 'git-pull' except that it preserves linear history with 'git-rebase' instead of -'git-merge' for ease of dcommit-ing with git-svn. +'git-merge' for ease of dcommiting with git-svn. This accepts all options that 'git-svn fetch' and 'git-rebase' accepts. However '--fetch-all' only fetches from the current @@ -434,6 +440,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 --------------------- @@ -458,6 +484,38 @@ the user on the git side. git-svn does however follow copy history of the directory that it is tracking, however (much like how 'svn log' works). +CAVEATS +------- + +For the sake of simplicity and interoperating with a less-capable system +(SVN), it is recommended that all git-svn users clone, fetch and dcommit +directly from the SVN server, and avoid all git-clone/pull/merge/push +operations between git repositories and branches. The recommended +method of exchanging code between git branches and users is +git-format-patch and git-am, or just dcommiting to the SVN repository. + +Running 'git-merge' or 'git-pull' is NOT recommended on a branch you +plan to dcommit from. Subversion does not represent merges in any +reasonable or useful fashion; so users using Subversion cannot see any +merges you've made. Furthermore, if you merge or pull from a git branch +that is a mirror of an SVN branch, dcommit may commit to the wrong +branch. + +'git-clone' does not clone branches under the refs/remotes/ hierarchy or +any git-svn metadata, or config. So repositories created and managed with +using git-svn should use rsync(1) for cloning, if cloning is to be done +at all. + +Since 'dcommit' uses rebase internally, any git branches you git-push to +before dcommit on will require forcing an overwrite of the existing ref +on the remote repository. This is generally considered bad practice, +see the git-push(1) documentation for details. + +Do not use the --amend option of git-commit(1) on a change you've +already dcommitted. It is considered bad practice to --amend commits +you've already pushed to a remote repository for other users, and +dcommit with SVN is analogous to that. + BUGS ---- @@ -493,7 +551,7 @@ listed below are allowed: Keep in mind that the '*' (asterisk) wildcard of the local ref (left of the ':') *must* be the farthest right path component; however the remote wildcard may be anywhere as long as it's own -independent path componet (surrounded by '/' or EOL). This +independent path component (surrounded by '/' or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using gitlink:git-config[1] diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt index bdae7d87dc..71aad8b45b 100644 --- a/Documentation/git-svnimport.txt +++ b/Documentation/git-svnimport.txt @@ -68,6 +68,9 @@ When importing incrementally, you might need to edit the .git/svn2git file. Prepend 'rX: ' to commit messages, where X is the imported subversion revision. +-u:: + Replace underscores in tag names with periods. + -I <ignorefile_name>:: Import the svn:ignore directory property to files with this name in each directory. (The Subversion and GIT ignore @@ -174,4 +177,3 @@ Documentation by Matthias Urlichs <smurf@smurf.noris.de>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 4e3e02756c..119117f0bd 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -11,8 +11,8 @@ SYNOPSIS [verse] 'git-tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] <name> [<head>] 'git-tag' -d <name>... -'git-tag' -l [<pattern>] -'git-tag' -v <name> +'git-tag' [-n [<num>]] -l [<pattern>] +'git-tag' -v <name>... DESCRIPTION ----------- @@ -23,7 +23,7 @@ Unless `-f` is given, the tag must not yet exist in If one of `-a`, `-s`, or `-u <key-id>` is passed, the command creates a 'tag' object, and requires the tag message. Unless -`-m <msg>` is given, an editor is started for the user to type +`-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. Otherwise just the SHA1 object name of the commit object is @@ -38,8 +38,8 @@ GnuPG key for signing. `-v <tag>` verifies the gpg signature of the tag. -`-l <pattern>` lists tags that match the given pattern (or all -if no pattern is given). +`-l <pattern>` lists tags with names that match the given pattern +(or all if no pattern is given). OPTIONS ------- @@ -59,10 +59,17 @@ OPTIONS Delete existing tags with the given names. -v:: - Verify the gpg signature of given the tag + Verify the gpg signature of the given tag names. + +-n <num>:: + <num> specifies how many lines from the annotation, if any, + are printed when using -l. + The default is not to print any annotation lines. + If no number is given to `-n`, only the first line is printed. -l <pattern>:: - List tags that match the given pattern (or all if no pattern is given). + List tags with names that match the given pattern (or all if no pattern is given). + Typing "git tag" without arguments, also lists all tags. -m <msg>:: Use the given tag message (instead of prompting) diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index 7bde73b1b8..434607bfb5 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -42,16 +42,13 @@ OPTIONS CONFIGURATION ------------- -By default, file and directories modes are set to 0666 or 0777. It is -possible to change this by setting the "umask" variable in the -repository configuration as follows : -[tar] - umask = 002 ;# group friendly - -The special umask value "user" indicates that the user's current umask -will be used instead. The default value is 002, which means group -readable/writable files and directories. +tar.umask:: + This variable can be used to restrict the permission bits of + tar archive entries. The default is 0002, which turns off the + world write bit. The special value "user" indicates that the + archiving user's umask will be used instead. See umask(2) for + details. EXAMPLES -------- @@ -90,4 +87,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-unpack-file.txt b/Documentation/git-unpack-file.txt index 213dc8196b..20bb6a7800 100644 --- a/Documentation/git-unpack-file.txt +++ b/Documentation/git-unpack-file.txt @@ -33,4 +33,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index b1b3ec9772..d529a43f55 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -52,4 +52,3 @@ Documentation by Junio C Hamano GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 6cfbd9a842..0a1953803e 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -56,7 +56,7 @@ OPTIONS --unmerged:: If --refresh finds unmerged changes in the index, the default - behavior is to error out. This option makes git-update-index + behavior is to error out. This option makes git-update-index continue anyway. --ignore-missing:: @@ -64,12 +64,12 @@ OPTIONS --cacheinfo <mode> <object> <path>:: Directly insert the specified info into the index. - + --index-info:: Read index information from stdin. --chmod=(+|-)x:: - Set the execute permissions on the updated files. + Set the execute permissions on the updated files. --assume-unchanged, --no-assume-unchanged:: When these flags are specified, the object name recorded @@ -126,7 +126,7 @@ OPTIONS <file>:: Files to act on. Note that files beginning with '.' are discarded. This includes - `./file` and `dir/./file`. If you don't want this, then use + `./file` and `dir/./file`. If you don't want this, then use cleaner names. The same applies to directories ending '/' and paths with '//' @@ -324,4 +324,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 9424feab32..f222616591 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -7,7 +7,7 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- -'git-update-ref' [-m <reason>] (-d <ref> <oldvalue> | <ref> <newvalue> [<oldvalue>]) +'git-update-ref' [-m <reason>] (-d <ref> <oldvalue> | [--no-deref] <ref> <newvalue> [<oldvalue>]) DESCRIPTION ----------- @@ -36,6 +36,9 @@ them and update them as a regular file (i.e. it will allow the filesystem to follow them, but will overwrite such a symlink to somewhere else with a regular filename). +If --no-deref is given, <ref> itself is overwritten, rather than +the result of following the symbolic pointers. + In general, using git-update-ref HEAD "$head" diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 88a03c7c5e..e7e82a31ea 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -55,4 +55,3 @@ Documentation by Junio C Hamano. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 9b0de1c111..813942368b 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -62,4 +62,3 @@ Documentation by Eric Biederman and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 7a6132b016..f4c540f39b 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -51,4 +51,3 @@ Documentation by Junio C Hamano GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index 0f9bdb58dc..ac7fb19154 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -3,11 +3,11 @@ git-verify-tag(1) NAME ---- -git-verify-tag - Check the GPG signature of tag +git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- -'git-verify-tag' <tag> +'git-verify-tag' <tag>... DESCRIPTION ----------- @@ -29,4 +29,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index 399bff3bbc..607df48f09 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -78,4 +78,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt index 96d5e07b11..cb8d6aadeb 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -47,4 +47,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git.txt b/Documentation/git.txt index 98860af045..3b0d530257 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -9,8 +9,10 @@ git - the stupid content tracker SYNOPSIS -------- [verse] -'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [-p|--paginate] - [--bare] [--git-dir=GIT_DIR] [--help] COMMAND [ARGS] +'git' [--version] [--exec-path[=GIT_EXEC_PATH]] + [-p|--paginate|--no-pager] + [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE] + [--help] COMMAND [ARGS] DESCRIPTION ----------- @@ -41,9 +43,14 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.5.2/git.html[documentation for release 1.5.2] +* link:v1.5.2.5/git.html[documentation for release 1.5.2.5] * release notes for + link:RelNotes-1.5.2.5.txt[1.5.2.5], + link:RelNotes-1.5.2.4.txt[1.5.2.4], + link:RelNotes-1.5.2.3.txt[1.5.2.3], + link:RelNotes-1.5.2.2.txt[1.5.2.2], + link:RelNotes-1.5.2.1.txt[1.5.2.1], link:RelNotes-1.5.2.txt[1.5.2]. * link:v1.5.1.6/git.html[documentation for release 1.5.1.6] @@ -97,10 +104,21 @@ OPTIONS -p|--paginate:: Pipe all output into 'less' (or if set, $PAGER). +--no-pager:: + Do not pipe git output into a pager. + --git-dir=<path>:: Set the path to the repository. This can also be controlled by setting the GIT_DIR environment variable. +--work-tree=<path>:: + Set the path to the working tree. The value will not be + used in combination with repositories found automatically in + a .git directory (i.e. $GIT_DIR is not set). + This can also be controlled by setting the GIT_WORK_TREE + environment variable and the core.worktree configuration + variable. + --bare:: Same as --git-dir=`pwd`. @@ -345,6 +363,13 @@ git so take care if using Cogito etc. specifies a path to use instead of the default `.git` for the base of the repository. +'GIT_WORK_TREE':: + Set the path to the working tree. The value will not be + used in combination with repositories found automatically in + a .git directory (i.e. $GIT_DIR is not set). + This can also be controlled by the '--work-tree' command line + option and the core.worktree configuration variable. + git Commits ~~~~~~~~~~~ 'GIT_AUTHOR_NAME':: @@ -391,8 +416,41 @@ parameter, <path>. other ~~~~~ +'GIT_MERGE_VERBOSITY':: + A number controlling the amount of output shown by + the recursive merge strategy. Overrides merge.verbosity. + See gitlink:git-merge[1] + 'GIT_PAGER':: - This environment variable overrides `$PAGER`. + This environment variable overrides `$PAGER`. If it is set + 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, + git-whatchanged, etc., will force a flush of the output stream + after each commit-oriented record have been flushed. If this + variable is set to "0", the output of these commands will be done + using completely buffered I/O. If this environment variable is + not set, git will choose buffered or record-oriented flushing + based on whether stdout appears to be redirected to a file or not. 'GIT_TRACE':: If this variable is set to "1", "2" or "true" (comparison @@ -428,4 +486,3 @@ contributors on the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index d3ac9c7181..46f9d591aa 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -72,8 +72,8 @@ EFFECTS ------- Certain operations by git can be influenced by assigning -particular attributes to a path. Currently, three operations -are attributes-aware. +particular attributes to a path. Currently, the following +operations are attributes-aware. Checking-out and checking-in ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -199,7 +199,9 @@ Generating diff text ~~~~~~~~~~~~~~~~~~~~ The attribute `diff` affects if `git diff` generates textual -patch for the path or just says `Binary files differ`. +patch for the path or just says `Binary files differ`. It also +can affect what line is shown on the hunk header `@@ -k,l +n,m @@` +line. Set:: @@ -224,7 +226,8 @@ String:: Diff is shown using the specified custom diff driver. The driver program is given its input using the same calling convention as used for GIT_EXTERNAL_DIFF - program. + program. This name is also used for custom hunk header + selection. Defining a custom diff driver @@ -249,6 +252,50 @@ parameters, just like `GIT_EXTERNAL_DIFF` program is called. See gitlink:git[7] for details. +Defining a custom hunk-header +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each group of changes (called "hunk") in the textual diff output +is prefixed with a line of the form: + + @@ -k,l +n,m @@ TEXT + +The text is called 'hunk header', and by default a line that +begins with an alphabet, an underscore or a dollar sign is used, +which matches what GNU `diff -p` output uses. This default +selection however is not suited for some contents, and you can +use customized pattern to make a selection. + +First in .gitattributes, you would assign the `diff` attribute +for paths. + +------------------------ +*.tex diff=tex +------------------------ + +Then, you would define "diff.tex.funcname" configuration to +specify a regular expression that matches a line that you would +want to appear as the hunk header, like this: + +------------------------ +[diff "tex"] + funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$" +------------------------ + +Note. A single level of backslashes are eaten by the +configuration file parser, so you would need to double the +backslashes; the pattern above picks a line that begins with a +backslash, and zero or more occurrences of `sub` followed by +`section` followed by open brace, to the end of line. + +There are a few built-in patterns to make this easier, and `tex` +is one of them, so you do not have to write the above in your +configuration file (you still need to enable this with the +attribute mechanism, via `.gitattributes`). Another built-in +pattern is defined for `java` that defines a pattern suitable +for program text in Java language. + + Performing a three-way merge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -347,7 +394,7 @@ abc -foo -bar the attributes given to path `t/abc` are computed as follows: 1. By examining `t/.gitattributes` (which is in the same - diretory as the path in question), git finds that the first + directory as the path in question), git finds that the first line matches. `merge` attribute is set. It also finds that the second line matches, and attributes `foo` and `bar` are unset. @@ -358,12 +405,12 @@ 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. -As the result, the attributes assignement to `t/abc` becomes: +As the result, the attributes assignment to `t/abc` becomes: ---------------------------------------------------------------- foo set to true 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/gitk.txt b/Documentation/gitk.txt index 48c5894736..e9f82b97b9 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -99,4 +99,3 @@ Documentation by Junio C Hamano, Jonas Fonseca, and the git-list GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt new file mode 100644 index 0000000000..035294e208 --- /dev/null +++ b/Documentation/gitmodules.txt @@ -0,0 +1,62 @@ +gitmodules(5) +============= + +NAME +---- +gitmodules - defining submodule properties + +SYNOPSIS +-------- +gitmodules + + +DESCRIPTION +----------- + +The `.gitmodules` file, located in the top-level directory of a git +working tree, is a text file with a syntax matching the requirements +of gitlink:git-config[1]. + +The file contains one subsection per submodule, and the subsection value +is the name of the submodule. Each submodule section also contains the +following required keys: + +submodule.<name>.path:: + Defines the path, relative to the top-level directory of the git + working tree, where the submodule is expected to be checked out. + The path name must not end with a `/`. All submodule paths must + be unique within the .gitmodules file. + +submodule.<name>.url:: + Defines an url from where the submodule repository can be cloned. + + +EXAMPLES +-------- + +Consider the following .gitmodules file: + + [submodule "libfoo"] + path = include/foo + url = git://foo.com/git/lib.git + + [submodule "libbar"] + path = include/bar + url = git://bar.com/git/lib.git + + +This defines two submodules, `libfoo` and `libbar`. These are expected to +be checked out in the paths 'include/foo' and 'include/bar', and for both +submodules an url is specified which can be used for cloning the submodules. + +SEE ALSO +-------- +gitlink:git-submodule[1] gitlink:git-config[1] + +DOCUMENTATION +------------- +Documentation by Lars Hjemli <hjemli@gmail.com> + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt index aabb9750fd..c39edc57c4 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -12,11 +12,10 @@ This document describes the currently defined hooks. applypatch-msg -------------- -This hook is invoked by `git-applypatch` script, which is -typically invoked by `git-applymbox`. It takes a single +This hook is invoked by `git-am` script. It takes a single parameter, the name of the file that holds the proposed commit log message. Exiting with non-zero status causes -`git-applypatch` to abort before applying the patch. +`git-am` to abort before applying the patch. The hook is allowed to edit the message file in place, and can be used to normalize the message into some project standard @@ -29,8 +28,7 @@ The default 'applypatch-msg' hook, when enabled, runs the pre-applypatch -------------- -This hook is invoked by `git-applypatch` script, which is -typically invoked by `git-applymbox`. It takes no parameter, +This hook is invoked by `git-am`. It takes no parameter, and is invoked after the patch is applied, but before a commit is made. Exiting with non-zero status causes the working tree after application of the patch not committed. @@ -44,12 +42,11 @@ The default 'pre-applypatch' hook, when enabled, runs the post-applypatch --------------- -This hook is invoked by `git-applypatch` script, which is -typically invoked by `git-applymbox`. It takes no parameter, +This hook is invoked by `git-am`. It takes no parameter, and is invoked after the patch is applied and a commit is made. This hook is meant primarily for notification, and cannot affect -the outcome of `git-applypatch`. +the outcome of `git-am`. pre-commit ---------- @@ -179,7 +176,7 @@ hook does on its standard input. This hook does not affect the outcome of `git-receive-pack`, as it is called after the real work is done. -This supersedes the <<post-update,'post-update'>> hook in that it get's +This supersedes the <<post-update,'post-update'>> hook in that it gets both old and new values of all the refs in addition to their names. diff --git a/Documentation/howto/rebase-and-edit.txt b/Documentation/howto/rebase-and-edit.txt index 646c55cc69..554909fe08 100644 --- a/Documentation/howto/rebase-and-edit.txt +++ b/Documentation/howto/rebase-and-edit.txt @@ -9,16 +9,16 @@ Abstract: In this article, Linus demonstrates how a broken commit On Sat, 13 Aug 2005, Linus Torvalds wrote: -> That's correct. Same things apply: you can move a patch over, and create a -> new one with a modified comment, but basically the _old_ commit will be +> That's correct. Same things apply: you can move a patch over, and create a +> new one with a modified comment, but basically the _old_ commit will be > immutable. Let me clarify. You can entirely _drop_ old branches, so commits may be immutable, but -nothing forces you to keep them. Of course, when you drop a commit, you'll -always end up dropping all the commits that depended on it, and if you -actually got somebody else to pull that commit you can't drop it from +nothing forces you to keep them. Of course, when you drop a commit, you'll +always end up dropping all the commits that depended on it, and if you +actually got somebody else to pull that commit you can't drop it from _their_ repository, but undoing things is not impossible. For example, let's say that you've made a mess of things: you've committed @@ -29,7 +29,7 @@ want to save "b" and "c". What you can do is # for reference git branch broken - # Reset the main branch to three parents back: this + # Reset the main branch to three parents back: this # effectively undoes the three top commits git reset HEAD^^^ git checkout -f @@ -59,7 +59,7 @@ Finally, check out the end result again: to see that everything looks sensible. -And then, you can just remove the broken branch if you decide you really +And then, you can just remove the broken branch if you decide you really don't want it: # remove 'broken' branch @@ -68,8 +68,8 @@ don't want it: # Prune old objects if you're really really sure git prune -And yeah, I'm sure there are other ways of doing this. And as usual, the -above is totally untested, and I just wrote it down in this email, so if +And yeah, I'm sure there are other ways of doing this. And as usual, the +above is totally untested, and I just wrote it down in this email, so if I've done something wrong, you'll have to figure it out on your own ;) Linus @@ -77,5 +77,3 @@ I've done something wrong, you'll have to figure it out on your own ;) To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html - - diff --git a/Documentation/howto/rebase-from-internal-branch.txt b/Documentation/howto/rebase-from-internal-branch.txt index 3b3a5c2e69..7a76045eb7 100644 --- a/Documentation/howto/rebase-from-internal-branch.txt +++ b/Documentation/howto/rebase-from-internal-branch.txt @@ -14,10 +14,10 @@ Petr Baudis <pasky@suse.cz> writes: > Dear diary, on Sun, Aug 14, 2005 at 09:57:13AM CEST, I got a letter > where Junio C Hamano <junkio@cox.net> told me that... >> Linus Torvalds <torvalds@osdl.org> writes: ->> ->> > Junio, maybe you want to talk about how you move patches from your "pu" +>> +>> > Junio, maybe you want to talk about how you move patches from your "pu" >> > branch to the real branches. ->> +>> > Actually, wouldn't this be also precisely for what StGIT is intended to? Exactly my feeling. I was sort of waiting for Catalin to speak @@ -118,7 +118,7 @@ up your changes, along with other changes. where *your "master" head upstream --> #1 --> #2 --> #3 - used \ + used \ to be \--> #A --> #2' --> #3' --> #B --> #C *upstream head @@ -133,7 +133,7 @@ You fetch from upstream, but not merge. $ git fetch upstream This leaves the updated upstream head in .git/FETCH_HEAD but -does not touch your .git/HEAD nor .git/refs/heads/master. +does not touch your .git/HEAD nor .git/refs/heads/master. You run "git rebase" now. $ git rebase FETCH_HEAD master @@ -161,5 +161,3 @@ the #1' commit. To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html - - diff --git a/Documentation/howto/rebuild-from-update-hook.txt b/Documentation/howto/rebuild-from-update-hook.txt index 02621b54a0..8d55dfbfae 100644 --- a/Documentation/howto/rebuild-from-update-hook.txt +++ b/Documentation/howto/rebuild-from-update-hook.txt @@ -84,4 +84,3 @@ There are four things worth mentioning: - This is still crude and does not protect against simultaneous make invocations stomping on each other. I would need to add some locking mechanism for this. - diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt index d88ec23a97..865a666324 100644 --- a/Documentation/howto/revert-branch-rebase.txt +++ b/Documentation/howto/revert-branch-rebase.txt @@ -146,7 +146,7 @@ Everything is in the good order. I do not need the temporary branch nor tag anymore, so remove them: ------------------------------------------------ -$ rm -f .git/refs/tags/pu-anchor +$ rm -f .git/refs/tags/pu-anchor $ git branch -d revert-c99 ------------------------------------------------ diff --git a/Documentation/howto/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.txt index 090e2c9b01..0d73b31224 100644 --- a/Documentation/howto/separating-topic-branches.txt +++ b/Documentation/howto/separating-topic-branches.txt @@ -12,7 +12,7 @@ up with a history like this: "master" o---o - \ "topic" + \ "topic" o---o---o---o---o---o At this point, "topic" contains something I know I want, but it @@ -29,11 +29,11 @@ start building on top of "master": $ git checkout -b topicA master ... pick and apply pieces from P.diff to build ... commits on topicA branch. - + o---o---o / "topicA" o---o"master" - \ "topic" + \ "topic" o---o---o---o---o---o Before doing each commit on "topicA" HEAD, I run "diff HEAD" @@ -59,7 +59,7 @@ other topic: /o---o---o |/ "topicA" o---o"master" - \ "topic" + \ "topic" o---o---o---o---o---o After I am done, I'd try a pretend-merge between "topicA" and @@ -73,7 +73,7 @@ After I am done, I'd try a pretend-merge between "topicA" and /o---o---o----------' |/ "topicA" o---o"master" - \ "topic" + \ "topic" o---o---o---o---o---o The last diff better not to show anything other than cleanups @@ -84,8 +84,7 @@ for crufts. Then I can finally clean things up: "topicB" o---o---o---o---o - / + / /o---o---o |/ "topicA" o---o"master" - diff --git a/Documentation/howto/use-git-daemon.txt b/Documentation/howto/use-git-daemon.txt index 1a1eb246bf..4e2f75cb61 100644 --- a/Documentation/howto/use-git-daemon.txt +++ b/Documentation/howto/use-git-daemon.txt @@ -49,4 +49,3 @@ Now, test your daemon with $ git ls-remote git://127.0.0.1/rule-the-world.git If this does not work, find out why, and submit a patch to this document. - diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh index a64054948a..5433cf8ced 100755 --- a/Documentation/install-doc-quick.sh +++ b/Documentation/install-doc-quick.sh @@ -7,10 +7,10 @@ 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 +if ! git rev-parse --verify "$head^0" >/dev/null; then echo >&2 "head: $head does not exist in the current repository" usage fi @@ -18,14 +18,14 @@ fi GIT_INDEX_FILE=`pwd`/.quick-doc.index export GIT_INDEX_FILE rm -f "$GIT_INDEX_FILE" -git-read-tree $head -git-checkout-index -a -f --prefix="$mandir"/ +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/merge-options.txt b/Documentation/merge-options.txt index 182cef54be..d64c259bb3 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -1,3 +1,7 @@ +--summary:: + Show a diffstat at the end of the merge. The diffstat is also + controlled by the configuration option merge.diffstat. + -n, \--no-summary:: Do not show diffstat at the end of the merge. @@ -21,4 +25,3 @@ If there is no `-s` option, a built-in list of strategies is used instead (`git-merge-recursive` when merging a single head, `git-merge-octopus` otherwise). - diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index d922e8e86c..0193c3ce58 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -106,12 +106,14 @@ The placeholders are: - '%aD': author date, RFC2822 style - '%ar': author date, relative - '%at': author date, UNIX timestamp +- '%ai': author date, ISO 8601 format - '%cn': committer name - '%ce': committer email - '%cd': committer date - '%cD': committer date, RFC2822 style - '%cr': committer date, relative - '%ct': committer date, UNIX timestamp +- '%ci': committer date, ISO 8601 format - '%e': encoding - '%s': subject - '%b': body @@ -121,4 +123,3 @@ The placeholders are: - '%Creset': reset color - '%m': left, right or boundary mark - '%n': newline - diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 7d515be0fd..973d8dd733 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -1,9 +1,18 @@ --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 + name, show only handful hexdigits prefix. Non default number of + digits can be specified with "--abbrev=<n>" (which also modifies + diff output, if it is displayed). ++ +This should make "--pretty=oneline" a whole lot more readable for +people using 80-column terminals. --encoding[=<encoding>]:: The commit objects record the encoding used for the log message @@ -11,4 +20,3 @@ command to re-code the commit log message in the encoding preferred by the user. For non plumbing commands this defaults to UTF-8. - diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index 8d4e950abc..b6eb7fc618 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -58,7 +58,7 @@ is often useful. + Some short-cut notations are also supported. + -* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`; +* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`; it requests fetching everything up to the given tag. * A parameter <ref> without a colon is equivalent to <ref>: when pulling/fetching, so it merges <ref> into the current diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt index 15221b5320..4c92e375fe 100644 --- a/Documentation/repository-layout.txt +++ b/Documentation/repository-layout.txt @@ -177,4 +177,3 @@ shallow:: This is similar to `info/grafts` but is internally used and maintained by shallow clone mechanism. See `--depth` option to gitlink:git-clone[1] and gitlink:git-fetch[1]. - diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index 9ce3c473ae..e5b31c81fa 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -80,7 +80,7 @@ Pack Idx file: +--------------------------------+ | main | offset | | index | object name 00XXXXXXXXXXXXXXXX | | -table +--------------------------------+ | +table +--------------------------------+ | | offset | | | object name 00XXXXXXXXXXXXXXXX | | +--------------------------------+ | @@ -97,14 +97,14 @@ trailer | | packfile checksum | | +--------------------------------+ | | idxfile checksum | | +--------------------------------+ - .-------. + .-------. | Pack file entry: <+ packed object header: 1-byte size extension bit (MSB) type (next 3 bit) - size0 (lower 4-bit) + size0 (lower 4-bit) n-byte sizeN (as long as MSB is set, each 7-bit) size0..sizeN form 4+7+7+..+7 bit integer, size0 is the least significant part, and sizeN is the @@ -114,5 +114,5 @@ Pack file entry: <+ is the size before compression). If it is DELTA, then 20-byte base object name SHA1 (the size above is the - size of the delta data that follows). + size of the delta data that follows). delta data, deflated. diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 965ec00a6b..fff1068c54 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -339,7 +339,7 @@ $ git pull . remotes/bob/master ------------------------------------- Note that git pull always merges into the current branch, -regardless of what else is given on the commandline. +regardless of what else is given on the command line. Later, Bob can update his repo with Alice's latest changes using @@ -354,7 +354,7 @@ used for pulls: ------------------------------------- $ git config --get remote.origin.url -/home/bob/myrepo +/home/alice/project ------------------------------------- (The complete configuration created by git-clone is visible using diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt new file mode 100644 index 0000000000..5dd1f836c6 --- /dev/null +++ b/Documentation/urls-remotes.txt @@ -0,0 +1,55 @@ +include::urls.txt[] + +REMOTES +------- + +In addition to the above, as a short-hand, the name of a +file in `$GIT_DIR/remotes` directory can be given; the +named file should be in the following format: + +------------ + URL: one of the above URL format + Push: <refspec> + Pull: <refspec> + +------------ + +Then such a short-hand is specified in place of +<repository> without <refspec> parameters on the command +line, <refspec> specified on `Push:` lines or `Pull:` +lines are used for `git-push` and `git-fetch`/`git-pull`, +respectively. Multiple `Push:` and `Pull:` lines may +be specified for additional branch mappings. + +Or, equivalently, in the `$GIT_DIR/config` (note the use +of `fetch` instead of `Pull:`): + +------------ + [remote "<remote>"] + url = <url> + push = <refspec> + fetch = <refspec> + +------------ + +The name of a file in `$GIT_DIR/branches` directory can be +specified as an older notation short-hand; the named +file should contain a single line, a URL in one of the +above formats, optionally followed by a hash `#` and the +name of remote head (URL fragment notation). +`$GIT_DIR/branches/<remote>` file that stores a <url> +without the fragment is equivalent to have this in the +corresponding file in the `$GIT_DIR/remotes/` directory. + +------------ + URL: <url> + Pull: refs/heads/master:<remote> + +------------ + +while having `<url>#<head>` is equivalent to + +------------ + URL: <url> + Pull: refs/heads/<head>:<remote> +------------ diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 745f9677d0..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,62 +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/ =============================================================== -REMOTES -------- - -In addition to the above, as a short-hand, the name of a -file in `$GIT_DIR/remotes` directory can be given; the -named file should be in the following format: - ------------- - URL: one of the above URL format - Push: <refspec> - Pull: <refspec> - ------------- - -Then such a short-hand is specified in place of -<repository> without <refspec> parameters on the command -line, <refspec> specified on `Push:` lines or `Pull:` -lines are used for `git-push` and `git-fetch`/`git-pull`, -respectively. Multiple `Push:` and `Pull:` lines may -be specified for additional branch mappings. - -Or, equivalently, in the `$GIT_DIR/config` (note the use -of `fetch` instead of `Pull:`): - ------------- - [remote "<remote>"] - url = <url> - push = <refspec> - fetch = <refspec> - ------------- - -The name of a file in `$GIT_DIR/branches` directory can be -specified as an older notation short-hand; the named -file should contain a single line, a URL in one of the -above formats, optionally followed by a hash `#` and the -name of remote head (URL fragment notation). -`$GIT_DIR/branches/<remote>` file that stores a <url> -without the fragment is equivalent to have this in the -corresponding file in the `$GIT_DIR/remotes/` directory. - ------------- - URL: <url> - Pull: refs/heads/master:<remote> - ------------- - -while having `<url>#<head>` is equivalent to - ------------- - URL: <url> - Pull: refs/heads/<head>:<remote> ------------- +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 2e8c050bb1..06ab79fbd1 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1,10 +1,10 @@ -Git User's Manual (for version 1.5.1 or newer) +Git User's Manual (for version 1.5.3 or newer) ______________________________________________ Git is a fast distributed revision control system. -This manual is designed to be readable by someone with basic unix +This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of git. <<repositories-and-branches>> and <<exploring-git-history>> explain how @@ -208,7 +208,7 @@ commits will help understand how the git organizes history. In the following, we say that commit X is "reachable" from commit Y if commit X is an ancestor of commit Y. Equivalently, you could say -that Y is a descendent of X, or that there is a chain of parents +that Y is a descendant of X, or that there is a chain of parents leading from commit Y to commit X. [[history-diagrams]] @@ -440,7 +440,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 @@ -1048,7 +1048,7 @@ $ git show ------------------------------------------------- As a special shortcut, - + ------------------------------------------------- $ git commit -a ------------------------------------------------- @@ -1061,7 +1061,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. @@ -1070,6 +1070,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 ----------------------------- @@ -1221,7 +1226,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. @@ -1315,7 +1320,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 @@ -1448,6 +1453,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 ------------------------- @@ -1519,7 +1556,7 @@ history. Fortunately, git also keeps a log, called a "reflog", of all the previous values of each branch. So in this case you can still find the -old history using, for example, +old history using, for example, ------------------------------------------------- $ git log master@{1} @@ -1595,7 +1632,7 @@ If you decide you want the history back, you can always create a new reference pointing to it, for example, a new branch: ------------------------------------------------ -$ git branch recovered-branch 7281251ddd +$ git branch recovered-branch 7281251ddd ------------------------------------------------ Other types of dangling objects (blobs and trees) are also possible, and @@ -1631,24 +1668,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 @@ -1768,7 +1800,7 @@ like this: you push your personal repo ------------------> your public repo - ^ | + ^ | | | | you pull | they pull | | @@ -1844,7 +1876,7 @@ gitlink:git-update-server-info[1], and the documentation link:hooks.html[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 commandline like: +clone or pull from that url, for example with a command line like: ------------------------------------------------- $ git clone http://yourserver.com/~you/proj.git @@ -2343,7 +2375,7 @@ the result would create a new merge commit, like this: \ \ a--b--c--m <-- mywork ................................................ - + However, if you prefer to keep the history in mywork a simple series of commits without any merges, you may instead choose to use gitlink:git-rebase[1]: @@ -2445,8 +2477,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 gitlink: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: @@ -2463,7 +2497,7 @@ them again with gitlink:git-am[1]. Other tools ----------- -There are numerous other tools, such as stgit, which exist for the +There are numerous other tools, such as StGIT, which exist for the purpose of maintaining a patch series. These are outside of the scope of this manual. @@ -2719,7 +2753,7 @@ must have at least one root, and while you can tie several different root objects together into one project by creating a commit object which has two or more separate roots as its ultimate parents, that's probably just going to confuse people. So aim for the notion of "one root object -per project", even if git itself does not enforce that. +per project", even if git itself does not enforce that. A <<def_tag_object,"tag" object>> symbolically identifies and can be used to sign other objects. It contains the identifier and type of @@ -2938,15 +2972,15 @@ cache, and the normal operation is to re-generate it completely from a known tree object, or update/compare it with a live tree that is being developed. If you blow the directory cache away entirely, you generally haven't lost any information as long as you have the name of the tree -that it described. +that it described. -At the same time, the index is at the same time also the -staging area for creating new trees, and creating a new tree always -involves a controlled modification of the index file. In particular, -the index file can have the representation of an intermediate tree that -has not yet been instantiated. So the index can be thought of as a -write-back cache, which can contain dirty information that has not yet -been written back to the backing store. +At the same time, the index is also the staging area for creating +new trees, and creating a new tree always involves a controlled +modification of the index file. In particular, the index file can +have the representation of an intermediate tree that has not yet been +instantiated. So the index can be thought of as a write-back cache, +which can contain dirty information that has not yet been written back +to the backing store. @@ -2958,7 +2992,7 @@ Generally, all "git" operations work on the index file. Some operations work *purely* on the index file (showing the current state of the index), but most operations move data to and from the index file. Either from the database or from the working directory. Thus there are four -main combinations: +main combinations: [[working-directory-to-index]] working directory -> index @@ -3421,7 +3455,7 @@ because you interrupted a "git fetch" with ^C or something like that, leaving _some_ of the new objects in the object database, but just dangling and useless. -Anyway, once you are sure that you're not interested in any dangling +Anyway, once you are sure that you're not interested in any dangling state, you can just prune all unreachable objects: ------------------------------------------------ @@ -3432,12 +3466,12 @@ and they'll be gone. But you should only run "git prune" on a quiescent repository - it's kind of like doing a filesystem fsck recovery: you don't want to do that while the filesystem is mounted. -(The same is true of "git-fsck" itself, btw - but since -git-fsck never actually *changes* the repository, it just reports -on what it found, git-fsck itself is never "dangerous" to run. -Running it while somebody is actually changing the repository can cause -confusing and scary messages, but it won't actually do anything bad. In -contrast, running "git prune" while somebody is actively changing the +(The same is true of "git-fsck" itself, btw - but since +git-fsck never actually *changes* the repository, it just reports +on what it found, git-fsck itself is never "dangerous" to run. +Running it while somebody is actually changing the repository can cause +confusing and scary messages, but it won't actually do anything bad. In +contrast, running "git prune" while somebody is actively changing the repository is a *BAD* idea). [[birdview-on-the-source-code]] @@ -3893,8 +3927,8 @@ This is a work in progress. The basic requirements: - It must be readable in order, from beginning to end, by - someone intelligent with a basic grasp of the unix - commandline, but without any special knowledge of git. If + someone intelligent with a basic grasp of the UNIX + command line, but without any special knowledge of git. If necessary, any other prerequisites should be specifically mentioned as they arise. - Whenever possible, section headings should clearly describe |