Message-ID: <87lkjvhr2c.wl%cworth@cworth.org>
Date:	Mon, 22 Jan 2007 10:08:59 -0800
From:	Carl Worth <cworth@...rth.org>
To:	Junio C Hamano <junkio@....net>
Cc:	git@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [Announce] GIT v1.5.0-rc2

On Sun, 21 Jan 2007 03:20:06 -0800, Junio C Hamano wrote:
> Also, in the same spirit of giving the release an early
> exposure, here is the current draft of 1.5.0 release notes.

Thanks, these are very good and really show how much great progress
has gone into git recently. Congratulations to everyone who has helped
with this!

A few comments:

> In general, you should not have to worry about incompatibility,
> and there is no need to perform "repository conversion" if you
> are updating to v1.5.0.  However, some of the changes are
> one-way street upgrades; once you use them your repository
> can no longer be used with ancient git.

This "one-way street upgrades" sentence makes the upgrade to 1.5 sound
scarier than it really is. It's only after two more paragraphs of
fairly dense technical content that the reader is told that none of
this stuff is enabled by default yet.

Maybe replace the second sentence with something like:

	As of git v1.5.0 there are some optional changes to the
	repository that allow data to be stored and transferred more
	efficiently. These changes are not enabled by default as they
	will make the repository unusable with git versions before
	v1.4.2. Specifically the available options are:

or something along those lines.

>  - git-update-index is much less visible.

It's not clear what this sentence means. Perhaps add something like:

	, (many mentions of update-index in git output and
	documentation have now been replaced by simpler commands such
	as "git add" or "git rm").

>  - git-clone always uses what is known as "separate remote"
>    layout for a newly created repository with a working tree;
>    i.e. tracking branches in $GIT_DIR/refs/remotes/origin/ are
>    used to track branches from the origin.

This change has some workflow impact that is not at all obvious from
the above description. For example, after cloning git.git, things that
used to work like "git checkout -b my-next next" now no longer work,
(needing to use "origin/next" instead). And these branches also won't
appear in "git branch" output, (without the new -r option).

I think the release notes should spend a little more attention on an
issue like this. Maybe a separate section on changes to existing
interfaces, (as opposed to most of the other changes which are
improvements in the implementation of existing interfaces or just
plain new interfaces such as "git remote", "git gc", etc.)

If there is a new section, the previous paragraphs describing the move
of cloned origin information from .git/remotes/origin to .git/config
might belong there as well, (depending on whether you consider those
file contents a user-visible interface or not).

>  - git-branch and git-show-branch know remote tracking branches.

Should mention "-r" here.

>  - git-push can now be used to delete a remote branch or a tag.
>    This requires the updated git on the remote side.

What's the syntax for this? I know you don't want to turn the release
notes into a user manual, but it'd be nice to have brief mentions of
the new interfaces, (like the nice mention of "git add -i" for
example). Even with a quick skim through the git-push documentation,
I'm not immediately seeing how to delete a remote branch or tag.

>  - There is a toplevel garbage collector script, 'git-gc', that
>    is an easy way to run 'git-repack -a -d', 'git-reflog gc',
>    and 'git-prune'.

I think it's definitely worthwhile to note the fix of race conditions,
etc. here. It would be nice to have some short rule such as:

	"git gc" is free from any known race conditions with
	simultaneous git processes modifying the repository. So it's
	perfectly safe to run "git gc" from a cron job.

Or a similarly succinct rule that's actually true, (I think the recent
thread suggested "git gc" would only be safe with an extra
option---I'd much rather see it be safe by default and make the user
ask for extra unsafe pruning with an option).

>  - You can give non-branch to "git checkout" now.

Rather than "non-branch" I think it would be nice to say something
that mentioned tags. Maybe something like:

	You can now use 'git checkout' to checkout tags or any other
	revision, rather than just named branches."

>  - 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.

Is git-gc doing this housekeeping? If not, should it be? If so, should
it be mentioned here (and in the description of git-gc above)?

>  - 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.

Here's another description that could definitely benefit from a very
short example command.

-Carl

Content of type "application/pgp-signature" skipped

Powered by blists - more mailing lists