From: Junio C Hamano Date: Fri, 24 Oct 2014 21:57:51 +0000 (-0700) Subject: Merge branch 'po/doc-status-markup' X-Git-Tag: v2.2.0-rc0~23 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/f35a02b15d22521c4902d8b3434c7c55eeab4a1d?hp=7c45cee6bb3a9727d88fd8ea9c681d49fd29220e Merge branch 'po/doc-status-markup' Update documentation mark-up. * po/doc-status-markup: doc: fix 'git status --help' character quoting --- diff --git a/.gitignore b/.gitignore index 81e12c0621..a05241916c 100644 --- a/.gitignore +++ b/.gitignore @@ -74,6 +74,7 @@ /git-index-pack /git-init /git-init-db +/git-interpret-trailers /git-instaweb /git-log /git-ls-files @@ -178,6 +179,7 @@ /gitweb/static/gitweb.min.* /test-chmtime /test-ctype +/test-config /test-date /test-delta /test-dump-cache-tree @@ -198,6 +200,7 @@ /test-revision-walking /test-run-command /test-sha1 +/test-sha1-array /test-sigchain /test-string-list /test-subprocess diff --git a/Documentation/Makefile b/Documentation/Makefile index cea0e7ae3d..8d0f70938e 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -5,6 +5,7 @@ MAN7_TXT = TECH_DOCS = ARTICLES = SP_ARTICLES = +OBSOLETE_HTML = MAN1_TXT += $(filter-out \ $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ @@ -26,6 +27,7 @@ MAN7_TXT += gitcore-tutorial.txt MAN7_TXT += gitcredentials.txt MAN7_TXT += gitcvs-migration.txt MAN7_TXT += gitdiffcore.txt +MAN7_TXT += giteveryday.txt MAN7_TXT += gitglossary.txt MAN7_TXT += gitnamespaces.txt MAN7_TXT += gitrevisions.txt @@ -37,11 +39,11 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT)) MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT)) -OBSOLETE_HTML = git-remote-helpers.html +OBSOLETE_HTML += everyday.html +OBSOLETE_HTML += git-remote-helpers.html DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML) ARTICLES += howto-index -ARTICLES += everyday ARTICLES += git-tools ARTICLES += git-bisect-lk2009 # with their own formatting rules. diff --git a/Documentation/RelNotes/2.2.0.txt b/Documentation/RelNotes/2.2.0.txt new file mode 100644 index 0000000000..8d413feb8c --- /dev/null +++ b/Documentation/RelNotes/2.2.0.txt @@ -0,0 +1,263 @@ +Git v2.2 Release Notes +====================== + +Updates since v2.1 +------------------ + +Ports + + * Building on older MacOS X systems automatically sets + the necessary NO_APPLE_COMMON_CRYPTO build-time option. + + +UI, Workflows & Features + + * "git archive" learned to filter what gets archived with pathspec. + + * "git config --edit --global" starts from a skeletal per-user + configuration file contents, instead of a total blank, when the + user does not already have any. This immediately reduces the + need for a later "Have you forgotten setting core.user?" and we + can add more to the template as we gain more experience. + + * "git stash list -p" used to be almost always a no-op because each + stash entry is represented as a merge commit. It learned to show + the difference between the base commit version and the working tree + version, which is in line with what "git show" gives. + + * Sometimes users want to report a bug they experience on their + repository, but they are not at liberty to share the contents of + the repository. "fast-export" was taught an "--anonymize" option + to replace blob contents, names of people and paths and log + messages with bland and simple strings to help them. + + * "log --date=iso" uses a slight variant of ISO 8601 format that is + made more human readable. A new "--date=iso-strict" option gives + datetime output that is more strictly conformant. + + * A broken reimplementation of Git could write an invalid index that + records both stage #0 and higher stage entries for the same path. + We now notice and reject such an index, as there is no sensible + fallback (we do not know if the broken tool wanted to resolve and + forgot to remove higher stage entries, or if it wanted to unresolve + and forgot to remove the stage#0 entry). + + * The temporary files "git mergetool" uses are named to avoid too + many dots in them (e.g. a temporary file for "hello.c" used to be + named e.g. "hello.BASE.4321.c" but now uses underscore instead, + e.g. "hello_BASE_4321.c"). + + * The temporary files "git mergetools" uses can be placed in a newly + creted temporary directory, instead of the current directory, by + setting the mergetool.writeToTemp configuration variable. + + * The "pre-receive" and "post-receive" hooks are no longer required + to consume their input fully (not following this requirement used + to result in intermittent errors in "git push"). + + * The pretty-format specifier "%d", which expanded to " (tagname)" + for a tagged commit, gained a cousin "%D" that just gives the + "tagname" without frills. + + * "git push" learned "--signed" push, that allows a push (i.e. + request to update the refs on the other side to point at a new + history, together with the transmission of necessary objects) to be + signed, so that it can be verified and audited, using the GPG + signature of the person who pushed, that the tips of branches at a + public repository really point the commits the pusher wanted to, + without having to "trust" the server. + + * "git interpret-trailers" is a new filter to programatically edit + the tail end of the commit log messages. + + * "git help everyday" shows the "Everyday Git in 20 commands or so" + document, whose contents have been updated to more modern Git + practice. + + +Performance, Internal Implementation, etc. + + * The API to manipulate the "refs" has been restructured to make it + more transactional, with the eventual goal to allow all-or-none + atomic updates and migrating the storage to something other than + the traditional filesystem based one (e.g. databases). + + * The lockfile API and its users have been cleaned up. + + * We no longer attempt to keep track of individual dependencies to + the header files in the build procedure, relying on automated + dependency generation support from modern compilers. + + * In tests, we have been using NOT_{MINGW,CYGWIN} test prerequisites + long before negated prerequisites e.g. !MINGW were invented. + The former has been converted to the latter to avoid confusion. + + * Looking up remotes configuration in a repository with very many + remotes defined has been optimized. + + * There are cases where you lock and open to write a file, close it + to show the updated contents to external processes, and then have + to update the file again while still holding the lock, but the + lockfile API lacked support for such an access pattern. + + * The API to allocate the structure to keep track of commit + decoration has been updated to make it less cumbersome to use. + + * An in-core caching layer to let us avoid reading the same + configuration files number of times has been added. A few commands + have been converted to use this subsystem. + + * Various code paths have been cleaned up and simplified by using + "strbuf", "starts_with()", and "skip_prefix()" APIs more. + + * A few codepaths that died when large blobs that would not fit in + core are involved in their operation have been taught to punt + instead, by e.g. marking too large a blob as not to be diffed. + + * A few more code paths in "commit" and "checkout" have been taught + to repopulate the cache-tree in the index, to help speed up later + "write-tree" (used in "commit") and "diff-index --cached" (used in + "status"). + + * A common programming mistake to assign the same short option name + to two separate options is detected by parse_options() API to help + developers. + + * The code path to write out the packed-refs file has been optimized, + which especially matters in a repository with a large number of + refs. + + * The check to see if a ref $F can be created by making sure no + existing ref has $F/ as its prefix has been optimized, which + especially matters in a repository with a large number of existing + refs. + + * "git fsck" was taught to check contents of tag objects a bit more. + + * "git hash-object" was taught a "--literally" option to help + debugging. + + * When running a required clean filter, we do not have to mmap the + original before feeding the filter. Instead, stream the file + contents directly to the filter and process its output. + + * The scripts in the test suite can be run with "-x" option to show + a shell-trace of each command run in them. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.1 +---------------- + +Unless otherwise noted, all the fixes since v2.1 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * "git log --pretty/format=" with an empty format string did not + mean the more obvious "No output whatsoever" but "Use default + format", which was counterintuitive. + + * "git -c section.var command" and "git -c section.var= command" + should pass the configuration differently (the former should be a + boolean true, the latter should be an empty string). + + * Applying a patch not generated by Git in a subdirectory used to + check the whitespace breakage using the attributes for incorrect + paths. Also whitespace checks were performed even for paths + excluded via "git apply --exclude=" mechanism. + + * "git bundle create" with date-range specification were meant to + exclude tags outside the range, but it didn't. + + * "git add x" where x that used to be a directory has become a + symbolic link to a directory misbehaved. + + * The prompt script checked $GIT_DIR/ref/stash file to see if there + is a stash, which was a no-no. + + * Pack-protocol documentation had a minor typo. + + * "git checkout -m" did not switch to another branch while carrying + the local changes forward when a path was deleted from the index. + + * "git daemon" (with NO_IPV6 build configuration) used to incorrectly + use the hostname even when gethostbyname() reported that the given + hostname is not found. + (merge 107efbe rs/daemon-fixes later to maint). + + * With sufficiently long refnames, "git fast-import" could have + overflown an on-stack buffer. + + * After "pack-refs --prune" packed refs at the top-level, it failed + to prune them. + + * Progress output from "git gc --auto" was visible in "git fetch -q". + + * We used to pass -1000 to poll(2), expecting it to also mean "no + timeout", which should be spelled as -1. + + * "git rebase" documentation was unclear that it is required to + specify on what the rebase is to be done when telling it + to first check out . + (merge 95c6826 so/rebase-doc later to maint). + + * "git push" over HTTP transport had an artificial limit on number of + refs that can be pushed imposed by the command line length. + (merge 26be19b jk/send-pack-many-refspecs later to maint). + + * When receiving an invalid pack stream that records the same object + twice, multiple threads got confused due to a race. + (merge ab791dd jk/index-pack-threading-races later to maint). + + * An attempt to remove the entire tree in the "git fast-import" input + stream caused it to misbehave. + (merge 2668d69 mb/fast-import-delete-root later to maint). + + * Reachability check (used in "git prune" and friends) did not add a + detached HEAD as a starting point to traverse objects still in use. + (merge c40fdd0 mk/reachable-protect-detached-head later to maint). + + * "git config --add section.var val" used to lose existing + section.var whose value was an empty string. + (merge c1063be ta/config-add-to-empty-or-true-fix later to maint). + + * "git fsck" failed to report that it found corrupt objects via its + exit status in some cases. + (merge 30d1038 jk/fsck-exit-code-fix later to maint). + + * Use of "--verbose" option used to break "git branch --merged". + (merge 12994dd jk/maint-branch-verbose-merged later to maint). + + * Some MUAs mangled a line in a message that begins with "From " to + ">From " when writing to a mailbox file and feeding such an input + to "git am" used to lose such a line. + (merge 85de86a jk/mbox-from-line later to maint). + + * "rev-parse --verify --quiet $name" is meant to quietly exit with a + non-zero status when $name is not a valid object name, but still + gave error messages in some cases. + + * A handful of C source files have been updated to include + "git-compat-util.h" as the first thing, to conform better to our + coding guidelines. + (merge 1c4b660 da/include-compat-util-first-in-c later to maint). + + * t7004 test, which tried to run Git with small stack space, has been + updated to give a bit larger stack to avoid false breakage on some + platforms. + (merge b9a1907 sk/tag-contains-wo-recursion later to maint). + + * A few documentation pages had example sections marked up not quite + correctly, which passed AsciiDoc but failed with AsciiDoctor. + (merge c30c43c bc/asciidoc-pretty-formats-fix later to maint). + (merge f8a48af bc/asciidoc later to maint). + + * "gitweb" used deprecated CGI::startfrom, which was removed from + CGI.pm as of 4.04; use CGI::start_from instead. + (merge 4750f4b rm/gitweb-start-form later to maint). + + * Newer versions of 'meld' breaks the auto-detection we use to see if + they are new enough to support the `--output` option. + (merge b12d045 da/mergetool-meld later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index c55c22ab7b..400dcad21d 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -499,7 +499,8 @@ core.bigFileThreshold:: Files larger than this size are stored deflated, without attempting delta compression. Storing large files without delta compression avoids excessive memory usage, at the - slight expense of increased disk usage. + slight expense of increased disk usage. Additionally files + larger than this size are always treated as binary. + Default is 512 MiB on all platforms. This should be reasonable for most projects as source code and other text files can still @@ -1754,6 +1755,15 @@ mergetool..trustExitCode:: if the file has been updated, otherwise the user is prompted to indicate the success of the merge. +mergetool.meld.hasOutput:: + Older versions of `meld` do not support the `--output` option. + Git will attempt to detect whether `meld` supports `--output` + by inspecting the output of `meld --help`. Configuring + `mergetool.meld.hasOutput` will make Git skip these checks and + use the configured value instead. Setting `mergetool.meld.hasOutput` + to `true` tells Git to unconditionally use the `--output` option, + and `false` avoids using `--output`. + mergetool.keepBackup:: After performing a merge, the original file with conflict markers can be saved as a file with a `.orig` extension. If this variable @@ -1767,6 +1777,12 @@ mergetool.keepTemporaries:: preserved, otherwise they will be removed after the tool has exited. Defaults to `false`. +mergetool.writeToTemp:: + Git writes temporary 'BASE', 'LOCAL', and 'REMOTE' versions of + conflicting files in the worktree by default. Git will attempt + to use a temporary directory for these files when set `true`. + Defaults to `false`. + mergetool.prompt:: Prompt before each invocation of the merge resolution program. @@ -2043,6 +2059,25 @@ receive.autogc:: receiving data from git-push and updating refs. You can stop it by setting this variable to false. +receive.certnonceseed:: + By setting this variable to a string, `git receive-pack` + will accept a `git push --signed` and verifies it by using + a "nonce" protected by HMAC using this string as a secret + key. + +receive.certnonceslop:: + When a `git push --signed` sent a push certificate with a + "nonce" that was issued by a receive-pack serving the same + repository within this many seconds, export the "nonce" + found in the certificate to `GIT_PUSH_CERT_NONCE` to the + hooks (instead of what the receive-pack asked the sending + side to include). This may allow writing checks in + `pre-receive` and `post-receive` a bit easier. Instead of + checking `GIT_PUSH_CERT_NONCE_SLOP` environment variable + that records by how many seconds the nonce is stale to + decide if they want to accept the certificate, they only + can check `GIT_PUSH_CERT_NONCE_STATUS` is `OK`. + receive.fsckObjects:: If it is set to true, git-receive-pack will check all received objects. It will abort in the case of a malformed object or a diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt deleted file mode 100644 index b2548ef4e6..0000000000 --- a/Documentation/everyday.txt +++ /dev/null @@ -1,413 +0,0 @@ -Everyday Git With 20 Commands Or So -=================================== - -<> commands are essential for -anybody who makes a commit, even for somebody who works alone. - -If you work with other people, you will need commands listed in -the <> section as well. - -People who play the <> role need to learn some more -commands in addition to the above. - -<> commands are for system -administrators who are responsible for the care and feeding -of Git repositories. - - -Individual Developer (Standalone)[[Individual Developer (Standalone)]] ----------------------------------------------------------------------- - -A standalone individual developer does not exchange patches with -other people, and works alone in a single repository, using the -following commands. - - * linkgit:git-init[1] to create a new repository. - - * linkgit:git-show-branch[1] to see where you are. - - * linkgit:git-log[1] to see what happened. - - * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch - branches. - - * linkgit:git-add[1] to manage the index file. - - * linkgit:git-diff[1] and linkgit:git-status[1] to see what - you are in the middle of doing. - - * linkgit:git-commit[1] to advance the current branch. - - * linkgit:git-reset[1] and linkgit:git-checkout[1] (with - pathname parameters) to undo changes. - - * linkgit:git-merge[1] to merge between local branches. - - * linkgit:git-rebase[1] to maintain topic branches. - - * linkgit:git-tag[1] to mark known point. - -Examples -~~~~~~~~ - -Use a tarball as a starting point for a new repository.:: -+ ------------- -$ tar zxf frotz.tar.gz -$ cd frotz -$ git init -$ git add . <1> -$ git commit -m "import of frotz source tree." -$ git tag v2.43 <2> ------------- -+ -<1> add everything under the current directory. -<2> make a lightweight, unannotated tag. - -Create a topic branch and develop.:: -+ ------------- -$ git checkout -b alsa-audio <1> -$ edit/compile/test -$ git checkout -- curses/ux_audio_oss.c <2> -$ git add curses/ux_audio_alsa.c <3> -$ edit/compile/test -$ git diff HEAD <4> -$ git commit -a -s <5> -$ edit/compile/test -$ git reset --soft HEAD^ <6> -$ edit/compile/test -$ git diff ORIG_HEAD <7> -$ git commit -a -c ORIG_HEAD <8> -$ git checkout master <9> -$ git merge alsa-audio <10> -$ git log --since='3 days ago' <11> -$ git log v2.43.. curses/ <12> ------------- -+ -<1> create a new topic branch. -<2> revert your botched changes in `curses/ux_audio_oss.c`. -<3> you need to tell Git if you added a new file; removal and -modification will be caught if you do `git commit -a` later. -<4> to see what changes you are committing. -<5> commit everything as you have tested, with your sign-off. -<6> take the last commit back, keeping what is in the working tree. -<7> look at the changes since the premature commit we took back. -<8> redo the commit undone in the previous step, using the message -you originally wrote. -<9> switch to the master branch. -<10> merge a topic branch into your master branch. -<11> review commit logs; other forms to limit output can be -combined and include `--max-count=10` (show 10 commits), -`--until=2005-12-10`, etc. -<12> view only the changes that touch what's in `curses/` -directory, since `v2.43` tag. - - -Individual Developer (Participant)[[Individual Developer (Participant)]] ------------------------------------------------------------------------- - -A developer working as a participant in a group project needs to -learn how to communicate with others, and uses these commands in -addition to the ones needed by a standalone developer. - - * linkgit:git-clone[1] from the upstream to prime your local - repository. - - * linkgit:git-pull[1] and linkgit:git-fetch[1] from "origin" - to keep up-to-date with the upstream. - - * linkgit:git-push[1] to shared repository, if you adopt CVS - style shared repository workflow. - - * linkgit:git-format-patch[1] to prepare e-mail submission, if - you adopt Linux kernel-style public forum workflow. - -Examples -~~~~~~~~ - -Clone the upstream and work on it. Feed changes to upstream.:: -+ ------------- -$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6 -$ cd my2.6 -$ edit/compile/test; git commit -a -s <1> -$ git format-patch origin <2> -$ git pull <3> -$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4> -$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> -$ git reset --hard ORIG_HEAD <6> -$ git gc <7> -$ git fetch --tags <8> ------------- -+ -<1> repeat as needed. -<2> extract patches from your branch for e-mail submission. -<3> `git pull` fetches from `origin` by default and merges into the -current branch. -<4> immediately after pulling, look at the changes done upstream -since last time we checked, only in the -area we are interested in. -<5> fetch from a specific branch from a specific repository and merge. -<6> revert the pull. -<7> garbage collect leftover objects from reverted pull. -<8> from time to time, obtain official tags from the `origin` -and store them under `.git/refs/tags/`. - - -Push into another repository.:: -+ ------------- -satellite$ git clone mothership:frotz frotz <1> -satellite$ cd frotz -satellite$ git config --get-regexp '^(remote|branch)\.' <2> -remote.origin.url mothership:frotz -remote.origin.fetch refs/heads/*:refs/remotes/origin/* -branch.master.remote origin -branch.master.merge refs/heads/master -satellite$ git config remote.origin.push \ - master:refs/remotes/satellite/master <3> -satellite$ edit/compile/test/commit -satellite$ git push origin <4> - -mothership$ cd frotz -mothership$ git checkout master -mothership$ git merge satellite/master <5> ------------- -+ -<1> mothership machine has a frotz repository under your home -directory; clone from it to start a repository on the satellite -machine. -<2> clone sets these configuration variables by default. -It arranges `git pull` to fetch and store the branches of mothership -machine to local `remotes/origin/*` remote-tracking branches. -<3> arrange `git push` to push local `master` branch to -`remotes/satellite/master` branch of the mothership machine. -<4> push will stash our work away on `remotes/satellite/master` -remote-tracking branch on the mothership machine. You could use this -as a back-up method. -<5> on mothership machine, merge the work done on the satellite -machine into the master branch. - -Branch off of a specific tag.:: -+ ------------- -$ git checkout -b private2.6.14 v2.6.14 <1> -$ edit/compile/test; git commit -a -$ git checkout master -$ git format-patch -k -m --stdout v2.6.14..private2.6.14 | - git am -3 -k <2> ------------- -+ -<1> create a private branch based on a well known (but somewhat behind) -tag. -<2> forward port all changes in `private2.6.14` branch to `master` branch -without a formal "merging". - - -Integrator[[Integrator]] ------------------------- - -A fairly central person acting as the integrator in a group -project receives changes made by others, reviews and integrates -them and publishes the result for others to use, using these -commands in addition to the ones needed by participants. - - * linkgit:git-am[1] to apply patches e-mailed in from your - contributors. - - * linkgit:git-pull[1] to merge from your trusted lieutenants. - - * linkgit:git-format-patch[1] to prepare and send suggested - alternative to contributors. - - * linkgit:git-revert[1] to undo botched commits. - - * linkgit:git-push[1] to publish the bleeding edge. - - -Examples -~~~~~~~~ - -My typical Git day.:: -+ ------------- -$ git status <1> -$ git show-branch <2> -$ mailx <3> -& s 2 3 4 5 ./+to-apply -& s 7 8 ./+hold-linus -& q -$ git checkout -b topic/one master -$ git am -3 -i -s -u ./+to-apply <4> -$ compile/test -$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5> -$ git checkout topic/one && git rebase master <6> -$ git checkout pu && git reset --hard next <7> -$ git merge topic/one topic/two && git merge hold/linus <8> -$ git checkout maint -$ git cherry-pick master~4 <9> -$ compile/test -$ git tag -s -m "GIT 0.99.9x" v0.99.9x <10> -$ git fetch ko && git show-branch master maint 'tags/ko-*' <11> -$ git push ko <12> -$ git push ko v0.99.9x <13> ------------- -+ -<1> see what I was in the middle of doing, if any. -<2> see what topic branches I have and think about how ready -they are. -<3> read mails, save ones that are applicable, and save others -that are not quite ready. -<4> apply them, interactively, with my sign-offs. -<5> create topic branch as needed and apply, again with my -sign-offs. -<6> rebase internal topic branch that has not been merged to the -master or exposed as a part of a stable branch. -<7> restart `pu` every time from the next. -<8> and bundle topic branches still cooking. -<9> backport a critical fix. -<10> create a signed tag. -<11> make sure I did not accidentally rewind master beyond what I -already pushed out. `ko` shorthand points at the repository I have -at kernel.org, and looks like this: -+ ------------- -$ cat .git/remotes/ko -URL: kernel.org:/pub/scm/git/git.git -Pull: master:refs/tags/ko-master -Pull: next:refs/tags/ko-next -Pull: maint:refs/tags/ko-maint -Push: master -Push: next -Push: +pu -Push: maint ------------- -+ -In the output from `git show-branch`, `master` should have -everything `ko-master` has, and `next` should have -everything `ko-next` has. - -<12> push out the bleeding edge. -<13> push the tag out, too. - - -Repository Administration[[Repository Administration]] ------------------------------------------------------- - -A repository administrator uses the following tools to set up -and maintain access to the repository by developers. - - * linkgit:git-daemon[1] to allow anonymous download from - repository. - - * linkgit:git-shell[1] can be used as a 'restricted login shell' - for shared central repository users. - -link:howto/update-hook-example.html[update hook howto] has a good -example of managing a shared central repository. - - -Examples -~~~~~~~~ -We assume the following in /etc/services:: -+ ------------- -$ grep 9418 /etc/services -git 9418/tcp # Git Version Control System ------------- - -Run git-daemon to serve /pub/scm from inetd.:: -+ ------------- -$ grep git /etc/inetd.conf -git stream tcp nowait nobody \ - /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm ------------- -+ -The actual configuration line should be on one line. - -Run git-daemon to serve /pub/scm from xinetd.:: -+ ------------- -$ cat /etc/xinetd.d/git-daemon -# default: off -# description: The Git server offers access to Git repositories -service git -{ - disable = no - type = UNLISTED - port = 9418 - socket_type = stream - wait = no - user = nobody - server = /usr/bin/git-daemon - server_args = --inetd --export-all --base-path=/pub/scm - log_on_failure += USERID -} ------------- -+ -Check your xinetd(8) documentation and setup, this is from a Fedora system. -Others might be different. - -Give push/pull only access to developers.:: -+ ------------- -$ grep git /etc/passwd <1> -alice:x:1000:1000::/home/alice:/usr/bin/git-shell -bob:x:1001:1001::/home/bob:/usr/bin/git-shell -cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell -david:x:1003:1003::/home/david:/usr/bin/git-shell -$ grep git /etc/shells <2> -/usr/bin/git-shell ------------- -+ -<1> log-in shell is set to /usr/bin/git-shell, which does not -allow anything but `git push` and `git pull`. The users should -get an ssh access to the machine. -<2> in many distributions /etc/shells needs to list what is used -as the login shell. - -CVS-style shared repository.:: -+ ------------- -$ grep git /etc/group <1> -git:x:9418:alice,bob,cindy,david -$ cd /home/devo.git -$ ls -l <2> - lrwxrwxrwx 1 david git 17 Dec 4 22:40 HEAD -> refs/heads/master - drwxrwsr-x 2 david git 4096 Dec 4 22:40 branches - -rw-rw-r-- 1 david git 84 Dec 4 22:40 config - -rw-rw-r-- 1 david git 58 Dec 4 22:40 description - drwxrwsr-x 2 david git 4096 Dec 4 22:40 hooks - -rw-rw-r-- 1 david git 37504 Dec 4 22:40 index - drwxrwsr-x 2 david git 4096 Dec 4 22:40 info - drwxrwsr-x 4 david git 4096 Dec 4 22:40 objects - drwxrwsr-x 4 david git 4096 Nov 7 14:58 refs - drwxrwsr-x 2 david git 4096 Dec 4 22:40 remotes -$ ls -l hooks/update <3> - -r-xr-xr-x 1 david git 3536 Dec 4 22:40 update -$ cat info/allowed-users <4> -refs/heads/master alice\|cindy -refs/heads/doc-update bob -refs/tags/v[0-9]* david ------------- -+ -<1> place the developers into the same git group. -<2> and make the shared repository writable by the group. -<3> use update-hook example by Carl from Documentation/howto/ -for branch policy control. -<4> alice and cindy can push into master, only bob can push into doc-update. -david is the release manager and is the only person who can -create and push version tags. - -HTTP server to support dumb protocol transfer.:: -+ ------------- -dev$ git update-server-info <1> -dev$ ftp user@isp.example.com <2> -ftp> cp -r .git /home/user/myproject.git ------------- -+ -<1> make sure your info/refs and objects/info/packs are up-to-date -<2> upload to public HTTP server hosted by your ISP. diff --git a/Documentation/everyday.txto b/Documentation/everyday.txto new file mode 100644 index 0000000000..c5047d8f9b --- /dev/null +++ b/Documentation/everyday.txto @@ -0,0 +1,9 @@ +Everyday Git With 20 Commands Or So +=================================== + +This document has been moved to linkgit:giteveryday[1]. + +Please let the owners of the referring site know so that they can update the +link you clicked to get here. + +Thanks. diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt index d15db42d43..7051c6bdf8 100644 --- a/Documentation/git-credential-cache--daemon.txt +++ b/Documentation/git-credential-cache--daemon.txt @@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory SYNOPSIS -------- [verse] -git credential-cache--daemon +git credential-cache--daemon [--debug] DESCRIPTION ----------- @@ -21,6 +21,10 @@ for `git-credential-cache` clients. Clients may store and retrieve credentials. Each credential is held for a timeout specified by the client; once no credentials are held, the daemon exits. +If the `--debug` option is specified, the daemon does not close its +stderr stream, and may output extra diagnostics to it even after it has +begun listening for clients. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 221506b04b..dbe9a46833 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -105,6 +105,11 @@ marks the same across runs. in the commit (as opposed to just listing the files which are different from the commit's first parent). +--anonymize:: + Anonymize the contents of the repository while still retaining + the shape of the history and stored tree. See the section on + `ANONYMIZING` below. + --refspec:: Apply the specified refspec to each ref exported. Multiple of them can be specified. @@ -141,6 +146,62 @@ referenced by that revision range contains the string 'refs/heads/master'. +ANONYMIZING +----------- + +If the `--anonymize` option is given, git will attempt to remove all +identifying information from the repository while still retaining enough +of the original tree and history patterns to reproduce some bugs. The +goal is that a git bug which is found on a private repository will +persist in the anonymized repository, and the latter can be shared with +git developers to help solve the bug. + +With this option, git will replace all refnames, paths, blob contents, +commit and tag messages, names, and email addresses in the output with +anonymized data. Two instances of the same string will be replaced +equivalently (e.g., two commits with the same author will have the same +anonymized author in the output, but bear no resemblance to the original +author string). The relationship between commits, branches, and tags is +retained, as well as the commit timestamps (but the commit messages and +refnames bear no resemblance to the originals). The relative makeup of +the tree is retained (e.g., if you have a root tree with 10 files and 3 +trees, so will the output), but their names and the contents of the +files will be replaced. + +If you think you have found a git bug, you can start by exporting an +anonymized stream of the whole repository: + +--------------------------------------------------- +$ git fast-export --anonymize --all >anon-stream +--------------------------------------------------- + +Then confirm that the bug persists in a repository created from that +stream (many bugs will not, as they really do depend on the exact +repository contents): + +--------------------------------------------------- +$ git init anon-repo +$ cd anon-repo +$ git fast-import <../anon-stream +$ ... test your bug ... +--------------------------------------------------- + +If the anonymized repository shows the bug, it may be worth sharing +`anon-stream` along with a regular bug report. Note that the anonymized +stream compresses very well, so gzipping it is encouraged. If you want +to examine the stream to see that it does not contain any private data, +you can peruse it directly before sending. You may also want to try: + +--------------------------------------------------- +$ perl -pe 's/\d+/X/g' :: -Instead of initializing the repository where it is supposed to be, -place a filesytem-agnostic Git symbolic link there, pointing to the -specified path, and initialize a Git repository at the path. The -result is Git repository can be separated from working tree. If this -is reinitialization, the repository will be moved to the specified -path. +Instead of initializing the repository as a directory to either `$GIT_DIR` or +`./.git/`, create a text file there containing the path to the actual +repository. This file acts as filesystem-agnostic Git symbolic link to the +repository. ++ +If this is reinitialization, the repository will be moved to the specified path. --shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: @@ -72,60 +72,65 @@ repository. When specified, the config variable "core.sharedRepository" is set so that files and directories under `$GIT_DIR` are created with the requested permissions. When not specified, Git will use permissions reported by umask(2). - ++ The option can have the following values, defaulting to 'group' if no value is given: ++ +-- +'umask' (or 'false'):: - - 'umask' (or 'false'): Use permissions reported by umask(2). The default, - when `--shared` is not specified. +Use permissions reported by umask(2). The default, when `--shared` is not +specified. - - 'group' (or 'true'): Make the repository group-writable, (and g+sx, since - the git group may be not the primary group of all users). - This is used to loosen the permissions of an otherwise safe umask(2) value. - Note that the umask still applies to the other permission bits (e.g. if - umask is '0022', using 'group' will not remove read privileges from other - (non-group) users). See '0xxx' for how to exactly specify the repository - permissions. +'group' (or 'true'):: - - 'all' (or 'world' or 'everybody'): Same as 'group', but make the repository - readable by all users. +Make the repository group-writable, (and g+sx, since the git group may be not +the primary group of all users). This is used to loosen the permissions of an +otherwise safe umask(2) value. Note that the umask still applies to the other +permission bits (e.g. if umask is '0022', using 'group' will not remove read +privileges from other (non-group) users). See '0xxx' for how to exactly specify +the repository permissions. - - '0xxx': '0xxx' is an octal number and each file will have mode '0xxx'. - '0xxx' will override users' umask(2) value (and not only loosen permissions - as 'group' and 'all' does). '0640' will create a repository which is - group-readable, but not group-writable or accessible to others. '0660' will - create a repo that is readable and writable to the current user and group, - but inaccessible to others. +'all' (or 'world' or 'everybody'):: -By default, the configuration flag receive.denyNonFastForwards is enabled +Same as 'group', but make the repository readable by all users. + +'0xxx':: + +'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will +override users' umask(2) value (and not only loosen permissions as 'group' and +'all' does). '0640' will create a repository which is group-readable, but not +group-writable or accessible to others. '0660' will create a repo that is +readable and writable to the current user and group, but inaccessible to others. +-- + +By default, the configuration flag `receive.denyNonFastForwards` is enabled in shared repositories, so that you cannot force a non fast-forwarding push into it. -If you name a (possibly non-existent) directory at the end of the command -line, the command is run inside the directory (possibly after creating it). +If you provide a 'directory', the command is run inside it. If this directory +does not exist, it will be created. -- - TEMPLATE DIRECTORY ------------------ The template directory contains files and directories that will be copied to the `$GIT_DIR` after it is created. -The template directory used will (in order): +The template directory will be one of the following (in order): - - The argument given with the `--template` option. + - the argument given with the `--template` option; - - The contents of the `$GIT_TEMPLATE_DIR` environment variable. + - the contents of the `$GIT_TEMPLATE_DIR` environment variable; - - The `init.templatedir` configuration variable. + - the `init.templatedir` configuration variable; or - - The default template directory: `/usr/share/git-core/templates`. + - the default template directory: `/usr/share/git-core/templates`. -The default template directory includes some directory structure, some -suggested "exclude patterns", and copies of sample "hook" files. -The suggested patterns and hook files are all modifiable and extensible. +The default template directory includes some directory structure, suggested +"exclude patterns" (see linkgit:gitignore[5]), and sample hook files (see linkgit:githooks[5]). EXAMPLES -------- @@ -136,10 +141,12 @@ Start a new Git repository for an existing code base:: $ cd /path/to/my/codebase $ git init <1> $ git add . <2> +$ git commit <3> ---------------- + -<1> prepare /path/to/my/codebase/.git directory -<2> add all existing file to the index +<1> Create a /path/to/my/codebase/.git directory. +<2> Add all existing files to the index. +<3> Record the pristine state as the first commit in the history. GIT --- diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt new file mode 100644 index 0000000000..81fac3d26d --- /dev/null +++ b/Documentation/git-interpret-trailers.txt @@ -0,0 +1,314 @@ +git-interpret-trailers(1) +========================= + +NAME +---- +git-interpret-trailers - help add stuctured information into commit messages + +SYNOPSIS +-------- +[verse] +'git interpret-trailers' [--trim-empty] [(--trailer [(=|:)])...] [...] + +DESCRIPTION +----------- +Help adding 'trailers' lines, that look similar to RFC 822 e-mail +headers, at the end of the otherwise free-form part of a commit +message. + +This command reads some patches or commit messages from either the + arguments or the standard input if no is specified. Then +this command applies the arguments passed using the `--trailer` +option, if any, to the commit message part of each input file. The +result is emitted on the standard output. + +Some configuration variables control the way the `--trailer` arguments +are applied to each commit message and the way any existing trailer in +the commit message is changed. They also make it possible to +automatically add some trailers. + +By default, a '=' or ':' argument given +using `--trailer` will be appended after the existing trailers only if +the last trailer has a different (, ) pair (or if there +is no existing trailer). The and parts will be trimmed +to remove starting and trailing whitespace, and the resulting trimmed + and will appear in the message like this: + +------------------------------------------------ +token: value +------------------------------------------------ + +This means that the trimmed and will be separated by +`': '` (one colon followed by one space). + +By default the new trailer will appear at the end of all the existing +trailers. If there is no existing trailer, the new trailer will appear +after the commit message part of the ouput, and, if there is no line +with only spaces at the end of the commit message part, one blank line +will be added before the new trailer. + +Existing trailers are extracted from the input message by looking for +a group of one or more lines that contain a colon (by default), where +the group is preceded by one or more empty (or whitespace-only) lines. +The group must either be at the end of the message or be the last +non-whitespace lines before a line that starts with '---'. Such three +minus signs start the patch part of the message. + +When reading trailers, there can be whitespaces before and after the +token, the separator and the value. There can also be whitespaces +indide the token and the value. + +Note that 'trailers' do not follow and are not intended to follow many +rules for RFC 822 headers. For example they do not follow the line +folding rules, the encoding rules and probably many other rules. + +OPTIONS +------- +--trim-empty:: + If the part of any trailer contains only whitespace, + the whole trailer will be removed from the resulting message. + This apply to existing trailers as well as new trailers. + +--trailer [(=|:)]:: + Specify a (, ) pair that should be applied as a + trailer to the input messages. See the description of this + command. + +CONFIGURATION VARIABLES +----------------------- + +trailer.separators:: + This option tells which characters are recognized as trailer + separators. By default only ':' is recognized as a trailer + separator, except that '=' is always accepted on the command + line for compatibility with other git commands. ++ +The first character given by this option will be the default character +used when another separator is not specified in the config for this +trailer. ++ +For example, if the value for this option is "%=$", then only lines +using the format '' with containing '%', '=' +or '$' and then spaces will be considered trailers. And '%' will be +the default separator used, so by default trailers will appear like: +'% ' (one percent sign and one space will appear between +the token and the value). + +trailer.where:: + This option tells where a new trailer will be added. ++ +This can be `end`, which is the default, `start`, `after` or `before`. ++ +If it is `end`, then each new trailer will appear at the end of the +existing trailers. ++ +If it is `start`, then each new trailer will appear at the start, +instead of the end, of the existing trailers. ++ +If it is `after`, then each new trailer will appear just after the +last trailer with the same . ++ +If it is `before`, then each new trailer will appear just before the +first trailer with the same . + +trailer.ifexists:: + This option makes it possible to choose what action will be + performed when there is already at least one trailer with the + same in the message. ++ +The valid values for this option are: `addIfDifferentNeighbor` (this +is the default), `addIfDifferent`, `add`, `overwrite` or `doNothing`. ++ +With `addIfDifferentNeighbor`, a new trailer will be added only if no +trailer with the same (, ) pair is above or below the line +where the new trailer will be added. ++ +With `addIfDifferent`, a new trailer will be added only if no trailer +with the same (, ) pair is already in the message. ++ +With `add`, a new trailer will be added, even if some trailers with +the same (, ) pair are already in the message. ++ +With `replace`, an existing trailer with the same will be +deleted and the new trailer will be added. The deleted trailer will be +the closest one (with the same ) to the place where the new one +will be added. ++ +With `doNothing`, nothing will be done; that is no new trailer will be +added if there is already one with the same in the message. + +trailer.ifmissing:: + This option makes it possible to choose what action will be + performed when there is not yet any trailer with the same + in the message. ++ +The valid values for this option are: `add` (this is the default) and +`doNothing`. ++ +With `add`, a new trailer will be added. ++ +With `doNothing`, nothing will be done. + +trailer..key:: + This `key` will be used instead of in the trailer. At + the end of this key, a separator can appear and then some + space characters. By default the only valid separator is ':', + but this can be changed using the `trailer.separators` config + variable. ++ +If there is a separator, then the key will be used instead of both the + and the default separator when adding the trailer. + +trailer..where:: + This option takes the same values as the 'trailer.where' + configuration variable and it overrides what is specified by + that option for trailers with the specified . + +trailer..ifexist:: + This option takes the same values as the 'trailer.ifexist' + configuration variable and it overrides what is specified by + that option for trailers with the specified . + +trailer..ifmissing:: + This option takes the same values as the 'trailer.ifmissing' + configuration variable and it overrides what is specified by + that option for trailers with the specified . + +trailer..command:: + This option can be used to specify a shell command that will + be called to automatically add or modify a trailer with the + specified . ++ +When this option is specified, the behavior is as if a special +'=' argument were added at the beginning of the command +line, where is taken to be the standard output of the +specified command with any leading and trailing whitespace trimmed +off. ++ +If the command contains the `$ARG` string, this string will be +replaced with the part of an existing trailer with the same +, if any, before the command is launched. ++ +If some '=' arguments are also passed on the command +line, when a 'trailer..command' is configured, the command will +also be executed for each of these arguments. And the part of +these arguments, if any, will be used to replace the `$ARG` string in +the command. + +EXAMPLES +-------- + +* Configure a 'sign' trailer with a 'Signed-off-by' key, and then + add two of these trailers to a message: ++ +------------ +$ git config trailer.sign.key "Signed-off-by" +$ cat msg.txt +subject + +message +$ cat msg.txt | git interpret-trailers --trailer 'sign: Alice ' --trailer 'sign: Bob ' +subject + +message + +Signed-off-by: Alice +Signed-off-by: Bob +------------ + +* Extract the last commit as a patch, and add a 'Cc' and a + 'Reviewed-by' trailer to it: ++ +------------ +$ git format-patch -1 +0001-foo.patch +$ git interpret-trailers --trailer 'Cc: Alice ' --trailer 'Reviewed-by: Bob ' 0001-foo.patch >0001-bar.patch +------------ + +* Configure a 'sign' trailer with a command to automatically add a + 'Signed-off-by: ' with the author information only if there is no + 'Signed-off-by: ' already, and show how it works: ++ +------------ +$ git config trailer.sign.key "Signed-off-by: " +$ git config trailer.sign.ifmissing add +$ git config trailer.sign.ifexists doNothing +$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"' +$ git interpret-trailers < EOF + +Signed-off-by: Bob +$ git interpret-trailers < Signed-off-by: Alice +> EOF + +Signed-off-by: Alice +------------ + +* Configure a 'fix' trailer with a key that contains a '#' and no + space after this character, and show how it works: ++ +------------ +$ git config trailer.separators ":#" +$ git config trailer.fix.key "Fix #" +$ echo "subject" | git interpret-trailers --trailer fix=42 +subject + +Fix #42 +------------ + +* Configure a 'see' trailer with a command to show the subject of a + commit that is related, and show how it works: ++ +------------ +$ git config trailer.see.key "See-also: " +$ git config trailer.see.ifExists "replace" +$ git config trailer.see.ifMissing "doNothing" +$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG" +$ git interpret-trailers < subject +> +> message +> +> see: HEAD~2 +> EOF +subject + +message + +See-also: fe3187489d69c4 (subject of related commit) +------------ + +* Configure a commit template with some trailers with empty values + (using sed to show and keep the trailing spaces at the end of the + trailers), then configure a commit-msg hook that uses + 'git interpret-trailers' to remove trailers with empty values and + to add a 'git-version' trailer: ++ +------------ +$ sed -e 's/ Z$/ /' >commit_template.txt < ***subject*** +> +> ***message*** +> +> Fixes: Z +> Cc: Z +> Reviewed-by: Z +> Signed-off-by: Z +> EOF +$ git config commit.template commit_template.txt +$ cat >.git/hooks/commit-msg < #!/bin/sh +> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" +> mv "\$1.new" "\$1" +> EOF +$ chmod +x .git/hooks/commit-msg +------------ + +SEE ALSO +-------- +linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 6738055bd3..9fed59a317 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -1,5 +1,5 @@ git-prune-packed(1) -===================== +=================== NAME ---- diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index c0d7403b9a..21b3f29c3b 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -10,7 +10,8 @@ SYNOPSIS -------- [verse] 'git push' [--all | --mirror | --tags] [--follow-tags] [-n | --dry-run] [--receive-pack=] - [--repo=] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream] + [--repo=] [-f | --force] [--prune] [-v | --verbose] + [-u | --set-upstream] [--signed] [--force-with-lease[=[:]]] [--no-verify] [ [...]] @@ -33,7 +34,7 @@ When the command line does not specify what to push with `...` arguments or `--all`, `--mirror`, `--tags` options, the command finds the default `` by consulting `remote.*.push` configuration, and if it is not found, honors `push.default` configuration to decide -what to push (See linkgit:git-config[1] for the meaning of `push.default`). +what to push (See gitlink:git-config[1] for the meaning of `push.default`). OPTIONS[[OPTIONS]] @@ -129,6 +130,12 @@ already exists on the remote side. from the remote but are pointing at commit-ish that are reachable from the refs being pushed. +--signed:: + GPG-sign the push request to update refs on the receiving + side, to allow it to be checked by the hooks and/or be + logged. See linkgit:git-receive-pack[1] for the details + on the receiving end. + --receive-pack=:: --exec=:: Path to the 'git-receive-pack' program on the remote diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index a356196586..d64388cb8e 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -1,5 +1,5 @@ git-quiltimport(1) -================ +================== NAME ---- diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 4138554912..924827dc2e 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -21,15 +21,17 @@ If is specified, 'git rebase' will perform an automatic it remains on the current branch. If is not specified, the upstream configured in -branch..remote and branch..merge options will be used; see -linkgit:git-config[1] for details. If you are currently not on any -branch or if the current branch does not have a configured upstream, -the rebase will abort. +branch..remote and branch..merge options will be used (see +linkgit:git-config[1] for details) and the `--fork-point` option is +assumed. If you are currently not on any branch or if the current +branch does not have a configured upstream, the rebase will abort. All changes made by commits in the current branch but that are not in are saved to a temporary area. This is the same set -of commits that would be shown by `git log ..HEAD` (or -`git log HEAD`, if --root is specified). +of commits that would be shown by `git log ..HEAD`; or by +`git log 'fork_point'..HEAD`, if `--fork-point` is active (see the +description on `--fork-point` below); or by `git log HEAD`, if the +`--root` option is specified. The current branch is reset to , or if the --onto option was supplied. This has the exact same effect as @@ -327,13 +329,18 @@ link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details) --fork-point:: --no-fork-point:: - Use 'git merge-base --fork-point' to find a better common ancestor - between `upstream` and `branch` when calculating which commits have - have been introduced by `branch` (see linkgit:git-merge-base[1]). + Use reflog to find a better common ancestor between + and when calculating which commits have been + introduced by . + -If no non-option arguments are given on the command line, then the default is -`--fork-point @{u}` otherwise the `upstream` argument is interpreted literally -unless the `--fork-point` option is specified. +When --fork-point is active, 'fork_point' will be used instead of + to calculate the set of commits to rebase, where +'fork_point' is the result of `git merge-base --fork-point +` command (see linkgit:git-merge-base[1]). If 'fork_point' +ends up being empty, the will be used as a fallback. ++ +If either or --root is given on the command line, then the +default is `--no-fork-point`, otherwise the default is `--fork-point`. --ignore-whitespace:: --whitespace=