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
Attachment:
pgp6qvbnhg7UR.pgp
Description: PGP signature