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>
This commit is contained in:
Junio C Hamano
parent
ea44949605
commit
26cfcfbff4
@ -32,6 +32,7 @@ man7dir=$(mandir)/man7
|
||||
# DESTDIR=
|
||||
|
||||
ASCIIDOC=asciidoc
|
||||
ASCIIDOC_EXTRA =
|
||||
INSTALL?=install
|
||||
DOC_REF = origin/man
|
||||
|
||||
@ -92,7 +93,7 @@ clean:
|
||||
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 $<
|
||||
|
||||
468
Documentation/RelNotes-1.5.0.txt
Normal file
468
Documentation/RelNotes-1.5.0.txt
Normal file
@ -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.
|
||||
@ -29,6 +29,24 @@ in a coherent way to git enlightenment ;-).
|
||||
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::
|
||||
|
||||
@ -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"
|
||||
|
||||
Loading…
Reference in New Issue
Block a user