[ANNOUNCE] GIT 1.5.5.1

[ANNOUNCE] GIT 1.5.5.1

[Junio C Hamano]

The latest maintenance release GIT 1.5.5.1 is available at the
usual places:

  http://www.kernel.org/pub/software/scm/git/

  git-1.5.5.1.tar.{gz,bz2}			(tarball)
  git-htmldocs-1.5.5.1.tar.{gz,bz2}		(preformatted docs)
  git-manpages-1.5.5.1.tar.{gz,bz2}		(preformatted docs)
  RPMS/$arch/git-*-1.5.5.1-1.$arch.rpm	(RPM)

Fortunately there weren't many brown paper bag breakages we needed to fix
immediately after releasing 1.5.5, but there do exist some usability and
documentation fixes accumulated on the maintenance branch.  This release
delibers them.

----------------------------------------------------------------

Changes since v1.5.5 are as follows:

Alberto Bertogli (1):
      builtin-apply: Show a more descriptive error on failure when opening a patch

Björn Steinbrink (1):
      Fix section about backdating tags in the git-tag docs

Carlos Rica (2):
      Fix documentation syntax of optional arguments in short options.
      core-tutorial.txt: Fix showing the current behaviour.

Christian Couder (4):
      bisect: fix bad rev checking in "git bisect good"
      bisect: report bad rev better
      bisect: squelch "fatal: ref HEAD not a symref" misleading message
      git-bisect: make "start", "good" and "skip" succeed or fail atomically

Clifford Caoile (1):
      Docs gitk: Explicitly mention the files that gitk uses (~/.gitk)

Daniel Barkalow (1):
      Fix config key miscount in url.*.insteadOf

Dirk Suesserott (1):
      Documentation/git-request-pull: Fixed a typo ("send" -> "end")

Jakub Narebski (1):
      gitweb: Fix 'history' view for deleted files with history

Jeff King (1):
      git-fetch: fix status output when not storing tracking ref

Johannes Sixt (1):
      Document option --only of git commit

Jon Loeliger (1):
      Clarify and fix English in "git-rm" documentation

Jonas Fonseca (1):
      git-remote: reject adding remotes with invalid names

Junio C Hamano (7):
      Document -w option to shortlog
      Documentation/git-submodule: typofix
      t7401: squelch garbage output
      rebase: do not munge commit log message
      git-am: minor cleanup
      am: POSIX portability fix
      GIT 1.5.5.1

Linus Torvalds (2):
      Ignore leading empty lines while summarizing merges
      git-am: cope better with an empty Subject: line

Mark Levedahl (1):
      git-submodule - possibly use branch name to describe a module

Matthieu Moy (1):
      Document that WebDAV doesn't need git on the server, and works over SSL

Michele Ballabio (1):
      revision.c: make --date-order overriddable

Pedro Melo (1):
      Force the medium pretty format on calls to git log

Ping Yin (1):
      git-submodule: Avoid 'fatal: cannot describe' message

René Scharfe (1):
      git-archive: ignore prefix when checking file attribute

Scott Collins (1):
      Clarify documentation of git-cvsserver, particularly in relation to git-shell

Shawn Bohrer (2):
      git clean: Don't automatically remove directories when run within subdirectory
      git clean: Add test to verify directories aren't removed with a prefix

Re: [ANNOUNCE] GIT 1.5.5.1

[Dmitry Potapov]

Hi Junio,

It looks like my patch to documentation has been lost. I sent
it about a week ago, and there has been no feedback to it, so
I believe it is okay.

The --prune option for 'git gc' was one of those options that you
need to use from time to time, but it was perceived by many users
as dangerous and many users were completely unaware of it, thus
often it was not used as intended.

Johannes' patch removed this option, which IMHO was a significant user
interface improvement.  Unfortunately, there are still a few places in
the documentation where this option is mentioned.  One of them is
"Everyday GIT", which is intended for beginners. I believe it is very
confusing for anyone who starts to use GIT to see an undocumented option
among recommended practice.

So, please, consider this patch for inclusion or provide any feedback
as to what kind of improvements may be needed for its inclusion.

Thanks,
Dmitry

-- >8 --
From: Dmitry Potapov <dpotapov@gmail.com>
Date: Mon, 14 Apr 2008 15:52:00 +0400
Subject: [PATCH] Documentation: git-gc --prune is deprecated

25ee9731c137d0a24b0f4879eb0b0cce9b77d5b0 made the '--prune' option
deprecated and removed its description from the git-gc man page. This
patch removes all references to this option from the rest of the Git
documentation.
---
 Documentation/everyday.txt    |    6 ++----
 Documentation/git-clone.txt   |   10 ++++++----
 Documentation/user-manual.txt |   17 +----------------
 3 files changed, 9 insertions(+), 24 deletions(-)

diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt
index fdbd15a..e598cdd 100644
--- a/Documentation/everyday.txt
+++ b/Documentation/everyday.txt
@@ -48,14 +48,12 @@ $ git gc <3>
 repository health reasonably well.
 <2> check how many loose objects there are and how much
 disk space is wasted by not repacking.
-<3> repacks the local repository and performs other housekeeping tasks. Running
-without `--prune` is a safe operation even while other ones are in progress.
+<3> repacks the local repository and performs other housekeeping tasks.
 
 Repack a small project into single pack.::
 +
 ------------
 $ git gc <1>
-$ git gc --prune
 ------------
 +
 <1> pack all the objects reachable from the refs into one pack,
@@ -182,7 +180,7 @@ $ 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 --prune <7>
+$ git gc <7>
 $ git fetch --tags <8>
 ------------
 +
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 9758243..c1bf814 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -65,10 +65,12 @@ OPTIONS
 +
 *NOTE*: this is a possibly dangerous operation; do *not* use
 it unless you understand what it does. If you clone your
-repository using this option, then delete branches in the
-source repository and then run linkgit:git-gc[1] using the
-'--prune' option in the source repository, it may remove
-objects which are referenced by the cloned repository.
+repository using this option and then delete a branch or use
+any other git command that makes any previous existing commit
+unreachable, then after some time linkgit:git-gc[1] may remove
+unreachable objects, and this will break the cloned repository.
+Because some git commands may run git-gc, it may happen at any
+time after gc.pruneExpire time since commits became unreachable.
 
 
 
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 565aeb9..86b91a5 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1548,22 +1548,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
 
 Dangling objects are not a problem.  At worst they may take up a little
 extra disk space.  They can sometimes provide a last-resort method for
-recovering lost work--see <<dangling-objects>> for details.  However, if
-you wish, you can remove them with linkgit:git-prune[1] or the `--prune`
-option to linkgit:git-gc[1]:
-
--------------------------------------------------
-$ git gc --prune
--------------------------------------------------
-
-This may be time-consuming.  Unlike most other git operations (including
-git-gc when run without any options), it is not safe to prune while
-other git operations are in progress in the same repository.
-
-If linkgit:git-fsck[1] complains about sha1 mismatches or missing
-objects, you may have a much more serious problem; your best option is
-probably restoring from backups.  See
-<<recovering-from-repository-corruption>> for a detailed discussion.
+recovering lost work--see <<dangling-objects>> for details.
 
 [[recovering-lost-changes]]
 Recovering lost changes
-- 
1.5.5

--

Re: [ANNOUNCE] GIT 1.5.5.1

[Brandon Casey]

Dmitry Potapov wrote:

> Johannes' patch removed this option, which IMHO was a significant user
> interface improvement.

Unless I missed something, this option has not been removed. The original
purpose for its existence (which was to cause git-gc to call git-prune)
has been removed. The call to git-prune within git-gc will remove _loose_
unreferenced objects, but _packed_ unreferenced objects are removed by
repack. The --prune option to git-gc is still used to adjust the call to
git-repack so that packed unreferenced objects are discarded.

> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index 9758243..c1bf814 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -65,10 +65,12 @@ OPTIONS
>  +
>  *NOTE*: this is a possibly dangerous operation; do *not* use
>  it unless you understand what it does. If you clone your
> -repository using this option, then delete branches in the
> -source repository and then run linkgit:git-gc[1] using the
> -'--prune' option in the source repository, it may remove
> -objects which are referenced by the cloned repository.
> +repository using this option and then delete a branch or use
> +any other git command that makes any previous existing commit
> +unreachable, then after some time linkgit:git-gc[1] may remove
> +unreachable objects, and this will break the cloned repository.
> +Because some git commands may run git-gc, it may happen at any
> +time after gc.pruneExpire time since commits became unreachable.

I agree that something should be said here about shared repositories,
but I think this wording is a little complicated (disclosure: I also
submitted some text for this a few weeks ago :). Of course something
is better than nothing.

Here's the blurb I submitted if you're interested:
+repository using this option and then delete branches in the
+source repository, some objects may become unreferenced (or dangling).
+These objects may be removed by normal git operations (such as git-commit[1])
+which automatically call git-gc[1]. If these objects are removed and
+were referenced by the cloned repository, then the cloned repository
+will become corrupt.

-brandon

Re: [ANNOUNCE] GIT 1.5.5.1

[Dmitry Potapov]

On Mon, Apr 21, 2008 at 07:23:10PM -0500, Brandon Casey wrote:
> Dmitry Potapov wrote:
> 
> > Johannes' patch removed this option, which IMHO was a significant user
> > interface improvement.
> 
> Unless I missed something, this option has not been removed. The original
> purpose for its existence (which was to cause git-gc to call git-prune)
> has been removed. The call to git-prune within git-gc will remove _loose_
> unreferenced objects, but _packed_ unreferenced objects are removed by
> repack. The --prune option to git-gc is still used to adjust the call to
> git-repack so that packed unreferenced objects are discarded.

I thought that it had no effect any more, because it had been removed
from the git-gc man page. Now I have looked at the code now, and it seems
the difference between running git gc with and without the prune option
is that with this option the git repack is called with '-a' option while
without it with '-A'. Unfortunately, the '-A' option in the git-repack
is also undocumented, but based on the reading git-repack.sh, you are
right. So, now I wonder wether removing the --prune option from the man
page was the right thing to do.

> 
> > diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> > index 9758243..c1bf814 100644
> > --- a/Documentation/git-clone.txt
> > +++ b/Documentation/git-clone.txt
> > @@ -65,10 +65,12 @@ OPTIONS
> >  +
> >  *NOTE*: this is a possibly dangerous operation; do *not* use
> >  it unless you understand what it does. If you clone your
> > -repository using this option, then delete branches in the
> > -source repository and then run linkgit:git-gc[1] using the
> > -'--prune' option in the source repository, it may remove
> > -objects which are referenced by the cloned repository.
> > +repository using this option and then delete a branch or use
> > +any other git command that makes any previous existing commit
> > +unreachable, then after some time linkgit:git-gc[1] may remove
> > +unreachable objects, and this will break the cloned repository.
> > +Because some git commands may run git-gc, it may happen at any
> > +time after gc.pruneExpire time since commits became unreachable.
> 
> I agree that something should be said here about shared repositories,
> but I think this wording is a little complicated (disclosure: I also
> submitted some text for this a few weeks ago :). Of course something
> is better than nothing.
> 
> Here's the blurb I submitted if you're interested:
> +repository using this option and then delete branches in the
> +source repository, some objects may become unreferenced (or dangling).
> +These objects may be removed by normal git operations (such as git-commit[1])
> +which automatically call git-gc[1]. If these objects are removed and
> +were referenced by the cloned repository, then the cloned repository
> +will become corrupt.

I like your wording better though I still prefer to mention that
deleting branches is just one of many possible commands that may
create unreferenced commits, i.e. something like that:

 ... repository using this option and then delete branches (or use any
 other git command that makes any existing commit unreferenced) ...


Dmitry

Re: [ANNOUNCE] GIT 1.5.5.1

[Brandon Casey]

Dmitry Potapov wrote:
> On Mon, Apr 21, 2008 at 07:23:10PM -0500, Brandon Casey wrote:
>> Dmitry Potapov wrote:
>>
>>> Johannes' patch removed this option, which IMHO was a significant user
>>> interface improvement.
>> Unless I missed something, this option has not been removed. The original
>> purpose for its existence (which was to cause git-gc to call git-prune)
>> has been removed. The call to git-prune within git-gc will remove _loose_
>> unreferenced objects, but _packed_ unreferenced objects are removed by
>> repack. The --prune option to git-gc is still used to adjust the call to
>> git-repack so that packed unreferenced objects are discarded.
> 
> I thought that it had no effect any more, because it had been removed
> from the git-gc man page. Now I have looked at the code now, and it seems
> the difference between running git gc with and without the prune option
> is that with this option the git repack is called with '-a' option while
> without it with '-A'. Unfortunately, the '-A' option in the git-repack
> is also undocumented, but based on the reading git-repack.sh, you are
> right. So, now I wonder wether removing the --prune option from the man
> page was the right thing to do.
> 
>>> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
>>> index 9758243..c1bf814 100644
>>> --- a/Documentation/git-clone.txt
>>> +++ b/Documentation/git-clone.txt
>>> @@ -65,10 +65,12 @@ OPTIONS
>>>  +
>>>  *NOTE*: this is a possibly dangerous operation; do *not* use
>>>  it unless you understand what it does. If you clone your
>>> -repository using this option, then delete branches in the
>>> -source repository and then run linkgit:git-gc[1] using the
>>> -'--prune' option in the source repository, it may remove
>>> -objects which are referenced by the cloned repository.
>>> +repository using this option and then delete a branch or use
>>> +any other git command that makes any previous existing commit
>>> +unreachable, then after some time linkgit:git-gc[1] may remove
>>> +unreachable objects, and this will break the cloned repository.
>>> +Because some git commands may run git-gc, it may happen at any
>>> +time after gc.pruneExpire time since commits became unreachable.
>> I agree that something should be said here about shared repositories,
>> but I think this wording is a little complicated (disclosure: I also
>> submitted some text for this a few weeks ago :). Of course something
>> is better than nothing.
>>
>> Here's the blurb I submitted if you're interested:
>> +repository using this option and then delete branches in the
>> +source repository, some objects may become unreferenced (or dangling).
>> +These objects may be removed by normal git operations (such as git-commit[1])
>> +which automatically call git-gc[1]. If these objects are removed and
>> +were referenced by the cloned repository, then the cloned repository
>> +will become corrupt.
> 
> I like your wording better though I still prefer to mention that
> deleting branches is just one of many possible commands that may
> create unreferenced commits, i.e. something like that:
> 
>  ... repository using this option and then delete branches (or use any
>  other git command that makes any existing commit unreferenced) ...

That's fine, but one of us needs to resubmit. Care to do the honors? :)

-brandon

Re: [ANNOUNCE] GIT 1.5.5.1

[Dmitry Potapov]

On Tue, Apr 22, 2008 at 12:37:44PM -0500, Brandon Casey wrote:
> Dmitry Potapov wrote:
> > 
> >  ... repository using this option and then delete branches (or use any
> >  other git command that makes any existing commit unreferenced) ...
> 
> That's fine, but one of us needs to resubmit. Care to do the honors? :)

Here it goes:

-- >8 --
From 21a905febd728f8839a1c96d0dfa83d8f252b132 Mon Sep 17 00:00:00 2001
From: Brandon Casey <casey@nrlssc.navy.mil>
Date: Thu, 3 Apr 2008 13:26:13 -0500
Subject: [PATCH] git-clone.txt: Adjust note to --shared for new pruning behavior of git-gc

Since git-gc now always calls prune, even with --auto, unreferenced objects
may be removed by more operations than just git-gc. This is important for
clones created using --shared or --reference.

Signed-off-by: Brandon Casey <casey@nrlssc.navy.mil>
Signed-off-by: Dmitry Potapov <dpotapov@gmail.com>
---
 Documentation/git-clone.txt |   13 +++++++++----
 1 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 9758243..9b56442 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -65,10 +65,13 @@ OPTIONS
 +
 *NOTE*: this is a possibly dangerous operation; do *not* use
 it unless you understand what it does. If you clone your
-repository using this option, then delete branches in the
-source repository and then run linkgit:git-gc[1] using the
-'--prune' option in the source repository, it may remove
-objects which are referenced by the cloned repository.
+repository using this option and then delete branches (or use any
+other git command that makes any existing commit unreferenced) in the
+source repository, some objects may become unreferenced (or dangling).
+These objects may be removed by normal git operations (such as git-commit[1])
+which automatically call git-gc[1]. If these objects are removed and
+were referenced by the cloned repository, then the cloned repository
+will become corrupt.
 
 
 
@@ -79,6 +82,8 @@ objects which are referenced by the cloned repository.
 	an already existing repository as an alternate will
 	require fewer objects to be copied from the repository
 	being cloned, reducing network and local storage costs.
++
+*NOTE*: see NOTE to --shared option.
 
 --quiet::
 -q::
-- 
1.5.5

--

Re: [ANNOUNCE] GIT 1.5.5.1

[Johannes Sixt]

Junio C Hamano schrieb:
> The latest maintenance release GIT 1.5.5.1 is available at the
> usual places:

Thanks a lot!

Note that the tag v1.5.5.1 is still missing from git://repo.or.cz/alt-git
(but it is present in other git.git sources).

-- Hannes