Add release notes to the distribution.
This also adds a hook in the Makefile I can use to automatically
include pointers to documentation for older releases when updating
the pages at http://kernel.org/pub/software/scm/git/docs/.
Signed-off-by: Junio C Hamano <junkio@cox.net>
diff --git a/Documentation/Makefile b/Documentation/Makefile
index aaf9591..9e7f2a7 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -32,6 +32,7 @@
# DESTDIR=
ASCIIDOC=asciidoc
+ASCIIDOC_EXTRA =
INSTALL?=install
DOC_REF = origin/man
@@ -92,7 +93,7 @@
rm -f $(cmds_txt)
%.html : %.txt
- $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $<
+ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $<
%.1 %.7 : %.xml
xmlto -m callouts.xsl man $<
diff --git a/Documentation/RelNotes-1.5.0.txt b/Documentation/RelNotes-1.5.0.txt
new file mode 100644
index 0000000..84e7eaf
--- /dev/null
+++ b/Documentation/RelNotes-1.5.0.txt
@@ -0,0 +1,468 @@
+GIT v1.5.0 Release Notes
+========================
+
+Old news
+--------
+
+This section is for people who are upgrading from ancient
+versions of git. Although all of the changes in this section
+happened before the current v1.4.4 release, they are summarized
+here in the v1.5.0 release notes for people who skipped earlier
+versions.
+
+As of git v1.5.0 there are some optional features that changes
+the repository to allow data to be stored and transferred more
+efficiently. These features are not enabled by default, as they
+will make the repository unusable with older versions of git.
+Specifically, the available options are:
+
+ - There is a configuration variable core.legacyheaders that
+ 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 clients over dumb transports (e.g. http) using older
+ versions of git will also be affected.
+
+ - Since v1.4.3, configuration repack.usedeltabaseoffset allows
+ packfile to be created in more space efficient format, which
+ cannot be read by git older than that version.
+
+The above two are not enabled by default and you explicitly have
+to ask for them, because these two features make repositories
+unreadable by older versions of git, and in v1.5.0 we still do
+not enable them by default for the same reason. We will change
+this default probably 1 year after 1.4.2's release, when it is
+reasonable to expect everybody to have new enough version of
+git.
+
+ - 'git pack-refs' appeared in v1.4.4; this command allows tags
+ to be accessed much more efficiently than the traditional
+ 'one-file-per-tag' format. Older git-native clients can
+ still fetch from a repository that packed and pruned refs
+ (the server side needs to run the up-to-date version of git),
+ but older dumb transports cannot. Packing of refs is done by
+ an explicit user action, either by use of "git pack-refs
+ --prune" command or by use of "git gc" command.
+
+ - 'git -p' to paginate anything -- many commands do pagination
+ by default on a tty. Introduced between v1.4.1 and v1.4.2;
+ this may surprise old timers.
+
+ - 'git archive' superseded 'git tar-tree' in v1.4.3;
+
+ - 'git cvsserver' was new invention in v1.3.0;
+
+ - 'git repo-config', 'git grep', 'git rebase' and 'gitk' were
+ seriously enhanced during v1.4.0 timeperiod.
+
+ - 'gitweb' became part of git.git during v1.4.0 timeperiod and
+ seriously modified since then.
+
+ - reflog is an v1.4.0 invention. This allows you to name a
+ revision that a branch used to be at (e.g. "git diff
+ master@{yesterday} master" allows you to see changes since
+ yesterday's tip of the branch).
+
+
+Updates in v1.5.0 since v1.4.4 series
+-------------------------------------
+
+* Index manipulation
+
+ - git-add is to add contents to the index (aka "staging area"
+ for the next commit), whether the file the contents happen to
+ be is an existing one or a newly created one.
+
+ - git-add without any argument does not add everything
+ anymore. Use 'git-add .' instead. Also you can add
+ otherwise ignored files with an -f option.
+
+ - git-add tries to be more friendly to users by offering an
+ interactive mode ("git-add -i").
+
+ - git-commit <path> used to refuse to commit if <path> was
+ different between HEAD and the index (i.e. update-index was
+ used on it earlier). This check was removed.
+
+ - git-rm is much saner and safer. It is used to remove paths
+ from both the index file and the working tree, and makes sure
+ you are not losing any local modification before doing so.
+
+ - git-reset <tree> <paths>... can be used to revert index
+ entries for selected paths.
+
+ - git-update-index is much less visible. Many suggestions to
+ use the command in git output and documentation have now been
+ replaced by simpler commands such as "git add" or "git rm".
+
+
+* Repository layout and objects transfer
+
+ - The data for origin repository is stored in the configuration
+ file $GIT_DIR/config, not in $GIT_DIR/remotes/, for newly
+ created clones. The latter is still supported and there is
+ no need to convert your existing repository if you are
+ already comfortable with your workflow with the layout.
+
+ - git-clone always uses what is known as "separate remote"
+ layout for a newly created repository with a working tree.
+
+ A repository with the separate remote layout starts with only
+ one default branch, 'master', to be used for your own
+ development. Unlike the traditional layout that copied all
+ the upstream branches into your branch namespace (while
+ renaming their 'master' to your 'origin'), the new layout
+ puts upstream branches into local "remote-tracking branches"
+ with their own namespace. These can be referenced with names
+ such as "origin/$upstream_branch_name" and are stored in
+ .git/refs/remotes rather than .git/refs/heads where normal
+ branches are stored.
+
+ This layout keeps your own branch namespace less cluttered,
+ avoids name collision with your upstream, makes it possible
+ to automatically track new branches created at the remote
+ after you clone from it, and makes it easier to interact with
+ more than one remote repository (you can use "git remote" to
+ add other repositories to track). There might be some
+ surprises:
+
+ * 'git branch' does not show the remote tracking branches.
+ It only lists your own branches. Use '-r' option to view
+ the tracking branches.
+
+ * If you are forking off of a branch obtained from the
+ upstream, you would have done something like 'git branch
+ my-next next', because traditional layout dropped the
+ tracking branch 'next' into your own branch namespace.
+ With the separate remote layout, you say 'git branch next
+ origin/next', which allows you to use the matching name
+ 'next' for your own branch. It also allows you to track a
+ remote other than 'origin' (i.e. where you initially cloned
+ from) and fork off of a branch from there the same way
+ (e.g. "git branch mingw j6t/master").
+
+ Repositories initialized with the traditional layout continue
+ to work.
+
+ - New branches that appear on the origin side after a clone is
+ made are also tracked automatically. This is done with an
+ wildcard refspec "refs/heads/*:refs/remotes/origin/*", which
+ older git does not understand, so if you clone with 1.5.0,
+ you would need to downgrade remote.*.fetch in the
+ configuration file to specify each branch you are interested
+ in individually if you plan to fetch into the repository with
+ older versions of git (but why would you?).
+
+ - Similarly, wildcard refspec "refs/heads/*:refs/remotes/me/*"
+ can be given to "git-push" command to update the tracking
+ branches that is used to track the repository you are pushing
+ from on the remote side.
+
+ - git-branch and git-show-branch know remote tracking branches
+ (use the command line switch "-r" to list only tracked branches).
+
+ - git-push can now be used to delete a remote branch or a tag.
+ This requires the updated git on the remote side (use "git
+ push <remote> :refs/heads/<branch>" to delete "branch").
+
+ - git-push more aggressively keeps the transferred objects
+ packed. Earlier we recommended to monitor amount of loose
+ objects and repack regularly, but you should repack when you
+ accumulated too many small packs this way as well. Updated
+ git-count-objects helps you with this.
+
+ - git-fetch also more aggressively keeps the transferred objects
+ packed. This behavior of git-push and git-fetch can be
+ tweaked with a single configuration transfer.unpacklimit (but
+ usually there should not be any need for a user to tweak it).
+
+ - A new command, git-remote, can help you manage your remote
+ tracking branch definitions.
+
+ - You may need to specify explicit paths for upload-pack and/or
+ receive-pack due to your ssh daemon configuration on the
+ other end. This can now be done via remote.*.uploadpack and
+ remote.*.receivepack configuration.
+
+
+* Bare repositories
+
+ - Certain commands change their behavior in a bare repository
+ (i.e. a repository without associated working tree). We use
+ a fairly conservative heuristic (if $GIT_DIR is ".git", or
+ ends with "/.git", the repository is not bare) to decide if a
+ repository is bare, but "core.bare" configuration variable
+ can be used to override the heuristic when it misidentifies
+ your repository.
+
+ - git-fetch used to complain updating the current branch but
+ this is now allowed for a bare repository. So is the use of
+ 'git-branch -f' to update the current branch.
+
+ - Porcelain-ish commands that require a working tree refuses to
+ work in a bare repository.
+
+
+* Reflog
+
+ - Reflog records the history from the view point of the local
+ repository. In other words, regardless of the real history,
+ the reflog shows the history as seen by one particular
+ repository (this enables you to ask "what was the current
+ revision in _this_ repository, yesterday at 1pm?"). This
+ facility is enabled by default for repositories with working
+ trees, and can be accessed with the "branch@{time}" and
+ "branch@{Nth}" notation.
+
+ - "git show-branch" learned showing the reflog data with the
+ new -g option. "git log" has -s option to view reflog
+ entries in a more verbose manner.
+
+ - git-branch knows how to rename branches and moves existing
+ reflog data from the old branch to the new one.
+
+ - In addition to the reflog support in v1.4.4 series, HEAD
+ reference maintains its own log. "HEAD@{5.minutes.ago}"
+ means the commit you were at 5 minutes ago, which takes
+ branch switching into account. If you want to know where the
+ tip of your current branch was at 5 minutes ago, you need to
+ explicitly say its name (e.g. "master@{5.minutes.ago}") or
+ omit the refname altogether i.e. "@{5.minutes.ago}".
+
+ - The commits referred to by reflog entries are now protected
+ against pruning. The new command "git reflog expire" can be
+ used to truncate older reflog entries and entries that refer
+ to commits that have been pruned away previously with older
+ versions of git.
+
+ Existing repositories that have been using reflog may get
+ complaints from fsck-objects and may not be able to run
+ git-repack, if you had run git-prune from older git; please
+ run "git reflog expire --stale-fix --all" first to remove
+ reflog entries that refer to commits that are no longer in
+ the repository when that happens.
+
+
+* Crufts removal
+
+ - We used to say "old commits are retrievable using reflog and
+ 'master@{yesterday}' syntax as long as you haven't run
+ git-prune". We no longer have to say the latter half of the
+ above sentence, as git-prune does not remove things reachable
+ from reflog entries.
+
+ - 'git-prune' by default does not remove _everything_
+ unreachable, as there is a one-day grace period built-in.
+
+ - There is a toplevel garbage collector script, 'git-gc', that
+ runs periodic cleanup functions, including 'git-repack -a -d',
+ 'git-reflog expire', 'git-pack-refs --prune', and 'git-rerere
+ gc'.
+
+ - The output from fsck ("fsck-objects" is called just "fsck"
+ now, but the old name continues to work) was needlessly
+ alarming in that it warned missing objects that are reachable
+ only from dangling objects. This has been corrected and the
+ output is much more useful.
+
+
+* Detached HEAD
+
+ - You can use 'git-checkout' to check out an arbitrary revision
+ or a tag as well, instead of named branches. This will
+ dissociate your HEAD from the branch you are currently on.
+
+ A typical use of this feature is to "look around". E.g.
+
+ $ git checkout v2.6.16
+ ... compile, test, etc.
+ $ git checkout v2.6.17
+ ... compile, test, etc.
+
+ - After detaching your HEAD, you can go back to an existing
+ branch with usual "git checkout $branch". Also you can
+ start a new branch using "git checkout -b $newbranch" to
+ start a new branch at that commit.
+
+ - You can even pull from other repositories, make merges and
+ commits while your HEAD is detached. Also you can use "git
+ reset" to jump to arbitrary commit, while still keeping your
+ HEAD detached.
+
+ Going back to attached state (i.e. on a particular branch) by
+ "git checkout $branch" can lose the current stat you arrived
+ in these ways, and "git checkout" refuses when the detached
+ HEAD is not pointed by any existing ref (an existing branch,
+ a remote tracking branch or a tag). This safety can be
+ overridden with "git checkout -f $branch".
+
+
+* Packed refs
+
+ - Repositories with hundreds of tags have been paying large
+ overhead, both in storage and in runtime, due to the
+ traditional one-ref-per-file format. A new command,
+ git-pack-refs, can be used to "pack" them in more efficient
+ representation (you can let git-gc do this for you).
+
+ - Clones and fetches over dumb transports are now aware of
+ packed refs and can download from repositories that use
+ them.
+
+
+* Configuration
+
+ - configuration related to color setting are consolidated under
+ color.* namespace (older diff.color.*, status.color.* are
+ still supported).
+
+ - 'git-repo-config' command is accessible as 'git-config' now.
+
+
+* Updated features
+
+ - git-describe uses better criteria to pick a base ref. It
+ used to pick the one with the newest timestamp, but now it
+ picks the one that is topologically the closest (that is,
+ among ancestors of commit C, the ref T that has the shortest
+ output from "git-rev-list T..C" is chosen).
+
+ - git-describe gives the number of commits since the base ref
+ between the refname and the hash suffix. E.g. the commit one
+ before v2.6.20-rc6 in the kernel repository is:
+
+ v2.6.20-rc5-306-ga21b069
+
+ which tells you that its object name begins with a21b069,
+ v2.6.20-rc5 is an ancestor of it (meaning, the commit
+ contains everything -rc5 has), and there are 306 commits
+ since v2.6.20-rc5.
+
+ - git-describe with --abbrev=0 can be used to show only the
+ name of the base ref.
+
+ - git-blame learned a new option, --incremental, that tells it
+ to output the blames as they are assigned. A sample script
+ to use it is also included as contrib/blameview.
+
+ - git-blame starts annotating from the working tree by default.
+
+
+* Less external dependency
+
+ - We no longer require the "merge" program from the RCS suite.
+ All 3-way file-level merges are now done internally.
+
+ - The original implementation of git-merge-recursive which was
+ in Python has been removed; we have a C implementation of it
+ now.
+
+ - git-shortlog is no longer a Perl script. It no longer
+ requires output piped from git-log; it can accept revision
+ parameters directly on the command line.
+
+
+* I18n
+
+ - We have always encouraged the commit message to be encoded in
+ UTF-8, but the users are allowed to use legacy encoding as
+ appropriate for their projects. This will continue to be the
+ case. However, a non UTF-8 commit encoding _must_ be
+ explicitly set with i18n.commitencoding in the repository
+ where a commit is made; otherwise git-commit-tree will
+ complain if the log message does not look like a valid UTF-8
+ string.
+
+ - The value of i18n.commitencoding in the originating
+ repository is recorded in the commit object on the "encoding"
+ header, if it is not UTF-8. git-log and friends notice this,
+ and reencodes the message to the log output encoding when
+ displaying, if they are different. The log output encoding
+ is determined by "git log --encoding=<encoding>",
+ i18n.logoutputencoding configuration, or i18n.commitencoding
+ configuration, in the decreasing order of preference, and
+ defaults to UTF-8.
+
+ - Tools for e-mailed patch application now default to -u
+ behavior; i.e. it always re-codes from the e-mailed encoding
+ to the encoding specified with i18n.commitencoding. This
+ unfortunately forces projects that have happily been using a
+ legacy encoding without setting i18n.commitencoding to set
+ the configuration, but taken with other improvement, please
+ excuse us for this very minor one-time inconvenience.
+
+
+* e-mailed patches
+
+ - See the above I18n section.
+
+ - git-format-patch now enables --binary without being asked.
+ git-am does _not_ default to it, as sending binary patch via
+ e-mail is unusual and is harder to review than textual
+ patches and it is prudent to require the person who is
+ applying the patch to explicitly ask for it.
+
+ - The default suffix for git-format-patch output is now ".patch",
+ not ".txt". This can be changed with --suffix=.txt option,
+ or setting the config variable "format.suffix" to ".txt".
+
+
+* Foreign SCM interfaces
+
+ - git-svn now requires the Perl SVN:: libraries, the
+ command-line backend was too slow and limited.
+
+ - the 'commit' subcommand of git-svn has been renamed to
+ 'set-tree', and 'dcommit' is the recommended replacement for
+ day-to-day work.
+
+ - git fast-import backend.
+
+
+* User support
+
+ - Quite a lot of documentation updates.
+
+ - Bash completion scripts have been updated heavily.
+
+ - Better error messages for often used Porcelainish commands.
+
+ - Git GUI. This is a simple Tk based graphical interface for
+ common Git operations.
+
+
+* Sliding mmap
+
+ - We used to assume that we can mmap the whole packfile while
+ in use, but with a large project this consumes huge virtual
+ memory space and truly huge ones would not fit in the
+ userland address space on 32-bit platforms. We now mmap huge
+ packfile in pieces to avoid this problem.
+
+
+* Shallow clones
+
+ - There is a partial support for 'shallow' repositories that
+ keeps only recent history. A 'shallow clone' is created by
+ specifying how deep that truncated history should be
+ (e.g. "git clone --depth=5 git://some.where/repo.git").
+
+ Currently a shallow repository has number of limitations:
+
+ - Cloning and fetching _from_ a shallow clone are not
+ supported (nor tested -- so they might work by accident but
+ they are not expected to).
+
+ - Pushing from nor into a shallow clone are not expected to
+ work.
+
+ - Merging inside a shallow repository would work as long as a
+ merge base is found in the recent history, but otherwise it
+ will be like merging unrelated histories and may result in
+ huge conflicts.
+
+ but this would be more than adequate for people who want to
+ look at near the tip of a big project with a deep history and
+ send patches in e-mail format.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 29ee24c..c0fa0d4 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -29,6 +29,24 @@
The COMMAND is either a name of a Git command (see below) or an alias
as defined in the configuration file (see gitlink:git-config[1]).
+ifdef::stalenotes[]
+[NOTE]
+============
+You are reading the documentation for the latest version of git.
+Documentation for older releases are available here:
+
+* link:v1.4.4.4/git.html[documentation for release 1.4.4.4]
+
+* link:v1.3.3/git.html[documentation for release 1.3.3]
+
+* link:v1.2.6/git.html[documentation for release 1.2.6]
+
+* link:v1.0.13/git.html[documentation for release 1.0.13]
+
+============
+
+endif::stalenotes[]
+
OPTIONS
-------
--version::
diff --git a/Documentation/install-webdoc.sh b/Documentation/install-webdoc.sh
index 60211a5..b398193 100755
--- a/Documentation/install-webdoc.sh
+++ b/Documentation/install-webdoc.sh
@@ -2,7 +2,7 @@
T="$1"
-for h in *.html *.txt howto/*.txt howto/*.html
+for h in *.html *.txt howto/*.txt howto/*.html RelNotes-*.txt
do
if test -f "$T/$h" &&
diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h"
diff --git a/RelNotes b/RelNotes
new file mode 120000
index 0000000..4571d0d
--- /dev/null
+++ b/RelNotes
@@ -0,0 +1 @@
+Documentation/RelNotes-1.5.0.txt
\ No newline at end of file
