--- /dev/null
+Git v1.8.1 Release Notes
+========================
+
+Backward compatibility notes
+----------------------------
+
+In the next major release (not *this* one), we will change the
+behavior of the "git push" command.
+
+When "git push [$there]" does not say what to push, we have used the
+traditional "matching" semantics so far (all your branches were sent
+to the remote as long as there already are branches of the same name
+over there). We will use the "simple" semantics that pushes the
+current branch to the branch with the same name, only when the current
+branch is set to integrate with that remote branch. There is a user
+preference configuration variable "push.default" to change this, and
+"git push" will warn about the upcoming change until you set this
+variable in this release.
+
+"git branch --set-upstream" is deprecated and may be removed in a
+relatively distant future. "git branch [-u|--set-upstream-to]" has
+been introduced with a saner order of arguments.
+
+
+Updates since v1.8.0
+--------------------
+
+UI, Workflows & Features
+
+ * We used to have a workaround for a bug in ancient "less" that
+ causes it to exit without any output when the terminal is resized.
+ The bug has been fixed in "less" version 406 (June 2007), and the
+ workaround has been removed in this release.
+
+ * A new configuration variable "diff.context" can be used to
+ give the default number of context lines in the patch output, to
+ override the hardcoded default of 3 lines.
+
+ * "git format-patch" leraned the "--notes=<ref>" option to give
+ notes for the commit after the three-dash lines in its output.
+
+ * "git log --grep=<pcre>" learned to honor the "grep.patterntype"
+ configuration set to "perl".
+
+ * "git rm $submodule" used to punt on removing a submodule working
+ tree to avoid losing the repository embedded in it. Because
+ recent git uses a mechanism to separate the submodule repository
+ from the submodule working tree, "git rm" learned to detect this
+ case and removes the submodule working tree when it is safe.
+
+ * "git submodule add" learned to add a new submodule at the same
+ path as the path where an unrelated submodule was bound to in an
+ existing revision via the "--name" option.
+
+ * "git submodule sync" learned the "--recursive" option.
+
+ * "git symbolic-ref" learned the "-d $symref" option to delete the
+ named symbolic ref, which is more intuitive way to spell it than
+ "update-ref -d --no-deref".
+
+
+Foreign Interface
+
+ * "git cvsimport" can be told to record timezones (other than GMT)
+ per-author via its author info file.
+
+ * The remote helper interface to interact with subversion
+ repositories (one of the GSoC 2012 projects) has been merged.
+
+
+Performance, Internal Implementation, etc.
+
+ * The logic to generate the initial advertisement from
+ "upload-pack" (what is invoked by "git fetch" on the other side
+ of the connection) to list what refs are available in the
+ repository has been optimized.
+
+ * The logic to find set of attributes that match a given path has
+ been optimized.
+
+
+Also contains minor documentation updates and code clean-ups.
+
+
+Fixes since v1.8.0
+------------------
+
+Unless otherwise noted, all the fixes since v1.8.0 in the maintenance
+track are contained in this release (see release notes to them for
+details).
+
+ * The configuration parser had an unnecessary hardcoded limit on
+ variable names that was not checked consistently.
+ (merge 0971e99 bw/config-lift-variable-name-length-limit later to maint).
+
+ * The "say" function in the test scaffolding incorrectly allowed
+ "echo" to interpret "\a" as if it were a C-string asking for a
+ BEL output.
+ (merge 7bc0911 jc/test-say-color-avoid-echo-escape later to maint).
+
+ * "git mergetool" feeds /dev/null as a common ancestor when dealing
+ with an add/add conflict, but p4merge backend cannot handle
+ it. Work it around by passing a temporary empty file.
+ (merge 3facc60 da/mergetools-p4 later to maint).
+
+ * "git log -F -E --grep='<ere>'" failed to use the given <ere>
+ pattern as extended regular expression, and instead looked for the
+ string literally.
+ (merge 727b6fc jc/grep-pcre-loose-ends~1 later to maint).
+
+ * "git grep -e pattern <tree>" asked the attribute system to read
+ "<tree>:.gitattributes" file in the working tree, which was
+ nonsense.
+ (merge 55c6168 nd/grep-true-path later to maint).
+
+ * A symbolic ref refs/heads/SYM was not correctly removed with "git
+ branch -d SYM"; the command removed the ref pointed by SYM
+ instead.
+ (merge 13baa9f rs/branch-del-symref later to maint).
+
+ * Update "remote tracking branch" in the documentation to
+ "remote-tracking branch".
+ (merge a6d3bde mm/maint-doc-remote-tracking later to maint).
+
+ * "git pull --rebase" run while the HEAD is detached tried to find
+ the upstream branch of the detached HEAD (which by definition
+ does not exist) and emitted unnecessary error messages.
+ (merge e980765 ph/pull-rebase-detached later to maint).
+
+ * The refs/replace hierarchy was not mentioned in the
+ repository-layout docs.
+ (merge 11fbe18 po/maint-refs-replace-docs later to maint).
+
+ * Various rfc2047 quoting issues around a non-ASCII name on the
+ From: line in the output from format-patch has been corrected.
+ (merge 25dc8da js/format-2047 later to maint).
+
+ * Sometimes curl_multi_timeout() function suggested a wrong timeout
+ value when there is no file descriptors to wait on and the http
+ transport ended up sleeping for minutes in select(2) system call.
+ A workaround has been added for this.
+ (merge 7202b81 sz/maint-curl-multi-timeout later to maint).
+
+ * For a fetch refspec (or the result of applying wildcard on one),
+ we always want the RHS to map to something inside "refs/"
+ hierarchy, but the logic to check it was not exactly right.
+ (merge 5c08c1f jc/maint-fetch-tighten-refname-check later to maint).
+
+ * "git diff -G<pattern>" did not honor textconv filter when looking
+ for changes.
+ (merge b1c2f57 jk/maint-diff-grep-textconv later to maint).