Draft of Git Rev News edition 5

Draft of Git Rev News edition 5

[Christian Couder]

Hi,

A draft of Git Rev News edition 5 is available here:

https://github.com/git/git.github.io/blob/master/rev_news/drafts/edition-5.md

Everyone is welcome to contribute in any section, like Junio and
Matthieu already did, either by editing the
above page on GitHub and sending a pull request, or by commenting on
this GitHub issue:

https://github.com/git/git.github.io/issues/77

You can also reply to this email.

I tried to cc everyone who appears in this edition but maybe I missed
some people, sorry about that.

Thomas, Nicola and myself plan to publish this edition on Wednesday
the 8th of July.

Thanks,
Christian.

Re: Draft of Git Rev News edition 5

[Eric Sunshine]

On Sun, Jul 05, 2015 at 01:13:57PM +0200, Christian Couder wrote:
> A draft of Git Rev News edition 5 is available here:
> https://github.com/git/git.github.io/blob/master/rev_news/drafts/edition-5.md
> Everyone is welcome to contribute in any section...

I'm not familiar with the criteria for deciding what merits mention
in the newsletter. Is the recent introduction of git-worktree and the
attendant relocation of "add" and "prune" functionality worthy? If
so, perhaps the following write-up would be suitable?

---- 8< ----
From: Eric Sunshine <sunshine@sunshineco.com>
Subject: [PATCH] rn-5: talk about new git-worktree command

---
 rev_news/drafts/edition-5.md | 60 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)

diff --git a/rev_news/drafts/edition-5.md b/rev_news/drafts/edition-5.md
index eb00c4a..9df4155 100644
--- a/rev_news/drafts/edition-5.md
+++ b/rev_news/drafts/edition-5.md
@@ -206,6 +206,63 @@ to process the format passed in `--date=format:...`, a discussion
 about how to manage a potential strftime() failure when it is passed a
 bogus format ensued.
 
+
+* Linked-worktrees
+
+The linked-worktree facility allows multiple working directories to share a
+single repository, with (typically) a different branch checked out in each
+worktree. Introduced more than half a year ago to provide integrated and
+platform-agnostic support for similar functionality long supplied by the
+Unix-only and somewhat fragile `contrib/git-new-workdir` script,
+linked-worktrees recently migrated to the *master* branch, but is not
+yet part of any release.
+
+Creation of linked-worktrees is accomplished via `git checkout --to <path>
+<branch>`, and cleanup of leftover administrative files, after `<path>` is
+deleted, is done with `git prune --worktrees`. However, a recent unrelated
+change to `git prune` led to a
+[discussion](http://article.gmane.org/gmane.comp.version-control.git/272546)
+that concluded that worktree-related maintenance functionality doesn't
+belong in `git prune`.
+
+Consequently, Nguyễn Thái Ngọc Duy submitted a
+[patch](http://thread.gmane.org/gmane.comp.version-control.git/272949)
+which introduces a new `git worktree` command, and relocates `git prune
+--worktrees` functionality to `git worktree prune`.
+
+Eric Sunshine then further fleshed out `git worktree` with a
+[patch](http://article.gmane.org/gmane.comp.version-control.git/273032)
+which relocates `git checkout --to` functionality to `git worktree new`.
+A lengthy
+[discussion](http://thread.gmane.org/gmane.comp.version-control.git/273032)
+ensued, which eventually led to a second version, consisting of [23
+patches](http://thread.gmane.org/gmane.comp.version-control.git/273316),
+and which names the command `git worktree add`, rather than `git worktree
+new`, and gives the documentation some needed attention.
+
+Aside from documentation updates, several other user-visible changes arrive
+with the second version. For instance, while preparing worktree-creation
+functionality for the move from `git checkout` to `git worktree`, Eric
+discovered and fixed a bug where `git checkout --to <path> HEAD~1` would
+instead incorrectly checkout `HEAD~2` at `<path>`.
+
+The second version also introduces convenience enhancements.  In
+particular, the `<branch>` in `git worktree add <path> <branch>`, is now
+optional. When omitted, a new branch is created automatically based upon
+`<path>`, as if `-b $(basename <path>)` had been provided (where `-b
+<new-branch>` creates a new branch). For example, given `git worktree add
+../hotfix`, a new branch named *hotfix* is created and checked out into new
+worktree `../hotfix`, as if `git worktree -b hotfix ../hotfix HEAD` had
+been specified.
+
+Finally, the question was
+[raised](http://article.gmane.org/gmane.comp.version-control.git/273107)
+whether `git checkout --ignore-other-worktrees` should be retired and `git
+checkout --force` overloaded to subsume its duties, however, Junio was [not
+thrilled](http://article.gmane.org/gmane.comp.version-control.git/273108)
+by the idea.
+
+
 ## Releases
 
 * [git-multimail](https://github.com/git-multimail/git-multimail) [1.1.0](https://github.com/git-multimail/git-multimail/releases/tag/1.1.0) was released. git-multimail is a tool to send notification emails for pushes to a git repository. It is also available in the `contrib/hooks/multimail/` directory of Git's source tree (version 1.1.0 will be distributed with Git 2.5).
@@ -282,5 +339,6 @@ __Git tools and sites__
 ## Credits
 
 This edition of Git Rev News was curated by Christian Couder &lt;<christian.couder@gmail.com>&gt;,
-Thomas Ferris Nicolaisen &lt;<tfnico@gmail.com>&gt; and Nicola Paolucci &lt;<npaolucci@atlassian.com>&gt;
+Thomas Ferris Nicolaisen &lt;<tfnico@gmail.com>&gt; Nicola Paolucci &lt;<npaolucci@atlassian.com>&gt;,
+and Eric Sunshine &lt;<sunshine@sunshineco.com>&gt;,
 with help from Junio C Hamano, Matthieu Moy and Johannes Schindelin.
-- 
2.5.0.rc1.197.g417e668

---- 8< ----

Re: Draft of Git Rev News edition 5

[Christian Couder]

On Sun, Jul 5, 2015 at 9:11 PM, Eric Sunshine <sunshine@sunshineco.com> wrote:
> On Sun, Jul 05, 2015 at 01:13:57PM +0200, Christian Couder wrote:
>> A draft of Git Rev News edition 5 is available here:
>> https://github.com/git/git.github.io/blob/master/rev_news/drafts/edition-5.md
>> Everyone is welcome to contribute in any section...
>
> I'm not familiar with the criteria for deciding what merits mention
> in the newsletter. Is the recent introduction of git-worktree and the
> attendant relocation of "add" and "prune" functionality worthy?

Yes, I think it's really worthy, thanks a lot for contributing this
very interesting article!

> If so, perhaps the following write-up would be suitable?

Yes, I changed a few things to make fit better with the rest of the
content, but otherwise it looks great!

I created this PR to discuss the changes I made:

https://github.com/git/git.github.io/pull/85

Thomas just merged it, but we can still discuss it.

Thanks again,
Christian.

Re: Draft of Git Rev News edition 5

[Eric Sunshine]

On Sun, Jul 5, 2015 at 5:13 PM, Christian Couder
<christian.couder@gmail.com> wrote:
> On Sun, Jul 5, 2015 at 9:11 PM, Eric Sunshine <sunshine@sunshineco.com> wrote:
>> On Sun, Jul 05, 2015 at 01:13:57PM +0200, Christian Couder wrote:
>>> A draft of Git Rev News edition 5 is available here:
>>> https://github.com/git/git.github.io/blob/master/rev_news/drafts/edition-5.md
>>> Everyone is welcome to contribute in any section...
>>
>> I'm not familiar with the criteria for deciding what merits mention
>> in the newsletter. Is the recent introduction of git-worktree and the
>> attendant relocation of "add" and "prune" functionality worthy?
>
> Yes, I think it's really worthy, thanks a lot for contributing this
> very interesting article!
>
>> If so, perhaps the following write-up would be suitable?
>
> Yes, I changed a few things to make fit better with the rest of the
> content, but otherwise it looks great!
>
> I created this PR to discuss the changes I made:
> https://github.com/git/git.github.io/pull/85

Thanks, for incorporating it. Unfortunately, the non-ASCII characters
in Duy's name got corrupted, and the botch is present in the patch I
sent. Sorry. Not sure how that happened. Can you fix it locally?

Re: Draft of Git Rev News edition 5

[Thomas Ferris Nicolaisen]

On Mon, Jul 6, 2015 at 12:01 AM, Eric Sunshine <sunshine@sunshineco.com> wrote:
> Unfortunately, the non-ASCII characters
> in Duy's name got corrupted, and the botch is present in the patch I
> sent. Sorry. Not sure how that happened. Can you fix it locally?

Fixed [1].

[1] https://github.com/git/git.github.io/commit/b5f7d6523ca6a634d568fc9017135ff2a9ea6462

Re: Draft of Git Rev News edition 5

[Eric Sunshine]

On Sun, Jul 5, 2015 at 6:35 PM, Thomas Ferris Nicolaisen
<tfnico@gmail.com> wrote:
> On Mon, Jul 6, 2015 at 12:01 AM, Eric Sunshine <sunshine@sunshineco.com> wrote:
>> Unfortunately, the non-ASCII characters
>> in Duy's name got corrupted, and the botch is present in the patch I
>> sent. Sorry. Not sure how that happened. Can you fix it locally?
>
> Fixed [1].
>
> [1] https://github.com/git/git.github.io/commit/b5f7d6523ca6a634d568fc9017135ff2a9ea6462

Thanks.

Re: Draft of Git Rev News edition 5

[Michael J Gruber]

Eric Sunshine venit, vidit, dixit 06.07.2015 01:12:
> On Sun, Jul 5, 2015 at 6:35 PM, Thomas Ferris Nicolaisen
> <tfnico@gmail.com> wrote:
>> On Mon, Jul 6, 2015 at 12:01 AM, Eric Sunshine <sunshine@sunshineco.com> wrote:
>>> Unfortunately, the non-ASCII characters
>>> in Duy's name got corrupted, and the botch is present in the patch I
>>> sent. Sorry. Not sure how that happened. Can you fix it locally?
>>
>> Fixed [1].
>>
>> [1] https://github.com/git/git.github.io/commit/b5f7d6523ca6a634d568fc9017135ff2a9ea6462
> 
> Thanks.
> 

Maybe a matter of taste, but I think in general we could do with a bit
less of "narrating" and more of "summarizing".

Just as an example, in the section on "visualizing merge diffs after the
fact", few people will be interested in the detail that I pointed out
the "--merges" option of rev-list to Dscho. While that recollection is
true and everything on the git-ml is public, I consider "Git Rev News"
to be "more public", targetted to a wider audience than the regulars.
They don't all know how much Git owes to Dscho. If things like this end
up in the news it makes me ponder for each on-list reply whether I'd
rather reply in private. Maybe I'm being overly sensitive (though not
affected in this case), but I just feel there are different degrees of
"public".

The pattern "...led to a discussion [between...] that resulted in..."
that we have in other places seems to be a good guideline.

Michael

Re: Draft of Git Rev News edition 5

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> Maybe a matter of taste, but I think in general we could do with a bit
> less of "narrating" and more of "summarizing".

True.

> Just as an example, in the section on "visualizing merge diffs after the
> fact", few people will be interested in the detail that I pointed out
> the "--merges" option of rev-list to Dscho. While that recollection is
> true and everything on the git-ml is public, I consider "Git Rev News"
> to be "more public", targetted to a wider audience than the regulars.
> They don't all know how much Git owes to Dscho. If things like this end
> up in the news it makes me ponder for each on-list reply whether I'd
> rather reply in private. Maybe I'm being overly sensitive (though not
> affected in this case), but I just feel there are different degrees of
> "public".

I do not see "Michael pointed out that there was a slightly better
way to do that" as saying anything bad about his contribution.

I however do agree with you that we want to see the newsletter aim
to summarize things better.  Instead of saying "Dscho suggested X,
Michael then refined it to Y", with full details of what X and Y
looked like, it would be more appropriate for the target audience to
say "Dscho and Michael worked together to come up with a solution
Y".

Re: Draft of Git Rev News edition 5

[Christian Couder]

On Wed, Jul 8, 2015 at 9:43 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
>
>> Maybe a matter of taste, but I think in general we could do with a bit
>> less of "narrating" and more of "summarizing".
>
> True.

I think sometimes the details might be interesting for different reasons.

>> Just as an example, in the section on "visualizing merge diffs after the
>> fact", few people will be interested in the detail that I pointed out
>> the "--merges" option of rev-list to Dscho. While that recollection is
>> true and everything on the git-ml is public, I consider "Git Rev News"
>> to be "more public", targetted to a wider audience than the regulars.
>> They don't all know how much Git owes to Dscho. If things like this end
>> up in the news it makes me ponder for each on-list reply whether I'd
>> rather reply in private. Maybe I'm being overly sensitive (though not
>> affected in this case), but I just feel there are different degrees of
>> "public".
>
> I do not see "Michael pointed out that there was a slightly better
> way to do that" as saying anything bad about his contribution.

On the contrary I think that the way Dscho used sed shows some cli
proficiency and might be interesting to some people.

> I however do agree with you that we want to see the newsletter aim
> to summarize things better.  Instead of saying "Dscho suggested X,
> Michael then refined it to Y", with full details of what X and Y
> looked like, it would be more appropriate for the target audience to
> say "Dscho and Michael worked together to come up with a solution
> Y".

With the details, I think readers are more likely to remember the
--merges option.

Re: Draft of Git Rev News edition 5

[Johannes Schindelin]

Hi,

On 2015-07-08 12:29, Christian Couder wrote:
> On Wed, Jul 8, 2015 at 9:43 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> Michael J Gruber <git@drmicha.warpmail.net> writes:
>>
>>> Just as an example, in the section on "visualizing merge diffs after the
>>> fact", few people will be interested in the detail that I pointed out
>>> the "--merges" option of rev-list to Dscho. While that recollection is
>>> true and everything on the git-ml is public, I consider "Git Rev News"
>>> to be "more public", targetted to a wider audience than the regulars.
>>> They don't all know how much Git owes to Dscho. If things like this end
>>> up in the news it makes me ponder for each on-list reply whether I'd
>>> rather reply in private. Maybe I'm being overly sensitive (though not
>>> affected in this case), but I just feel there are different degrees of
>>> "public".
>>
>> I do not see "Michael pointed out that there was a slightly better
>> way to do that" as saying anything bad about his contribution.
> 
> On the contrary I think that the way Dscho used sed shows some cli
> proficiency and might be interesting to some people.

Just for the record: I was really happy to learn about the --merges option. Also: I have not the faintest problem to demonstrate lack of knowledge publicly. It was kind of flattering to hear that my contributions to Git are appreciated, though ;-)

>> I however do agree with you that we want to see the newsletter aim
>> to summarize things better.  Instead of saying "Dscho suggested X,
>> Michael then refined it to Y", with full details of what X and Y
>> looked like, it would be more appropriate for the target audience to
>> say "Dscho and Michael worked together to come up with a solution
>> Y".
> 
> With the details, I think readers are more likely to remember the
> --merges option.

Yep, people remember things better when there is some story behind that they can relate to.

Ciao,
Dscho

Re: Draft of Git Rev News edition 5

[Junio C Hamano]

Christian Couder <christian.couder@gmail.com> writes:
>
> I think sometimes the details might be interesting for different reasons.
> ...
> With the details, I think readers are more likely to remember the
> --merges option.

That unfortunately cuts both ways.

With too much details, the readers are more likely to skim and skip
the "--merges" buried in reams of text.  Only the ones who carefully
read from cover to cover would discover and contrast the first
iteration "sed" with the second iteration "--merges", but I'd expect
that they would also be the ones who carefully read the docs and
more likely to know about "--merges" without Rev News teaching them.

Used sparingly, the details do pull interested readers in.  The key
word in your message was "sometimes", I think.

Re: Draft of Git Rev News edition 5

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> I'm not familiar with the criteria for deciding what merits mention
> in the newsletter. Is the recent introduction of git-worktree and the
> attendant relocation of "add" and "prune" functionality worthy? If
> so, perhaps the following write-up would be suitable?

One issue I had with this text was that it was not immediately clear
what the end-game UI of the feature was.  Is "checkout --to" they
way the user is expected to trigger this?  It appears in the very
early part of the multi-paragraph description and I suspect that the
majority of the users would think that way, not with "worktree add"
that appears a lot later.

Re: Draft of Git Rev News edition 5

[Eric Sunshine]

On Mon, Jul 6, 2015 at 12:38 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
>> I'm not familiar with the criteria for deciding what merits mention
>> in the newsletter. Is the recent introduction of git-worktree and the
>> attendant relocation of "add" and "prune" functionality worthy? If
>> so, perhaps the following write-up would be suitable?
>
> One issue I had with this text was that it was not immediately clear
> what the end-game UI of the feature was.  Is "checkout --to" they
> way the user is expected to trigger this?  It appears in the very
> early part of the multi-paragraph description and I suspect that the
> majority of the users would think that way, not with "worktree add"
> that appears a lot later.

I had the same concern when proof-reading, but wasn't sure if the
concern was warranted. Since you reacted to the text in the same way,
I'd say the concern was justified.

How about this instead: prefixing with "As originally implemented",
with a couple s/is/was/ thrown in...

    As originally implemented, creation of linked-worktrees was
    accomplished via `git checkout --to <path> <branch>`, and cleanup
    of leftover administrative files, after `<path>` is deleted, was
    done with `git prune --worktrees`. However, a recent unrelated
    change to `git prune` led to a discussion that concluded that
    worktree-related maintenance functionality didn't belong in `git
    prune`.

Is that sufficient to clue in the reader that "checkout --to" is not
final form, or should we mention "worktree add" and "worktree prune"
upfront?

Re: Draft of Git Rev News edition 5

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> How about this instead: prefixing with "As originally implemented",
> with a couple s/is/was/ thrown in...
>
>     As originally implemented, creation of linked-worktrees was
>     accomplished via `git checkout --to <path> <branch>`, and cleanup
>     of leftover administrative files, after `<path>` is deleted, was
>     done with `git prune --worktrees`. However, a recent unrelated
>     change to `git prune` led to a discussion that concluded that
>     worktree-related maintenance functionality didn't belong in `git
>     prune`.
>
> Is that sufficient to clue in the reader that "checkout --to" is not
> final form,...

Yeah, I think that is a good way to address my concern.

The current draft release notes to 2.5 mentions this feature as
experimental and warns that its UI is bound to change.  We will
ship the upcoming release with "checkout --to" and the more places
we advise the users that this UI is not final, the better.

Re: Draft of Git Rev News edition 5

[Eric Sunshine]

On Mon, Jul 06, 2015 at 10:54:28AM -0700, Junio C Hamano wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> > How about this instead: prefixing with "As originally implemented",
> > with a couple s/is/was/ thrown in...
> >
> >     As originally implemented, creation of linked-worktrees was
> >     accomplished via `git checkout --to <path> <branch>`, and cleanup
> >     of leftover administrative files, after `<path>` is deleted, was
> >     done with `git prune --worktrees`. However, a recent unrelated
> >     change to `git prune` led to a discussion that concluded that
> >     worktree-related maintenance functionality didn't belong in `git
> >     prune`.
> >
> > Is that sufficient to clue in the reader that "checkout --to" is not
> > final form,...
> 
> Yeah, I think that is a good way to address my concern.
> 
> The current draft release notes to 2.5 mentions this feature as
> experimental and warns that its UI is bound to change.  We will
> ship the upcoming release with "checkout --to" and the more places
> we advise the users that this UI is not final, the better.

Here it is in patch form. (I wouldn't be surprised if the non-ASCII
characters in Duy's name in the context line get botched again...)

---- 8< ----
From: Eric Sunshine <sunshine@sunshineco.com>
Subject: [PATCH] rn-5: make it clear that "git checkout --to" is not final
 form

We don't want to mislead reader who is only lightly skimming the text
or who doesn't read the entire article that "git checkout --to" is the
final form.
---
 rev_news/drafts/edition-5.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/rev_news/drafts/edition-5.md b/rev_news/drafts/edition-5.md
index 241e9df..b71c99c 100644
--- a/rev_news/drafts/edition-5.md
+++ b/rev_news/drafts/edition-5.md
@@ -35,12 +35,13 @@ Unix-only and somewhat fragile `contrib/git-new-workdir` script,
 linked-worktrees recently migrated to the *master* branch, but is not
 yet part of any release.
 
-Creation of linked-worktrees is accomplished via `git checkout --to <path>
-<branch>`, and cleanup of leftover administrative files, after `<path>` is
-deleted, is done with `git prune --worktrees`. However, a recent unrelated
-change to `git prune` led to a
+As originally implemented, creation of linked-worktrees was accomplished
+via `git checkout --to <path> <branch>`, and cleanup of leftover
+administrative files after manual deletion of `<path>` was done with `git
+prune --worktrees`. However, a recent unrelated change to `git prune` led
+to a
 [discussion](http://thread.gmane.org/gmane.comp.version-control.git/272447/focus=272546)
-that concluded that worktree-related maintenance functionality doesn't
+that concluded that worktree-related maintenance functionality didn't
 belong in `git prune`.
 
 Consequently, Nguyễn Thái Ngọc Duy submitted a
-- 
2.5.0.rc1.197.g417e668

Re: Draft of Git Rev News edition 5

[Christian Couder]

On Mon, Jul 6, 2015 at 9:39 PM, Eric Sunshine <sunshine@sunshineco.com> wrote:
> On Mon, Jul 06, 2015 at 10:54:28AM -0700, Junio C Hamano wrote:
>> Eric Sunshine <sunshine@sunshineco.com> writes:
>> > How about this instead: prefixing with "As originally implemented",
>> > with a couple s/is/was/ thrown in...
>> >
>> >     As originally implemented, creation of linked-worktrees was
>> >     accomplished via `git checkout --to <path> <branch>`, and cleanup
>> >     of leftover administrative files, after `<path>` is deleted, was
>> >     done with `git prune --worktrees`. However, a recent unrelated
>> >     change to `git prune` led to a discussion that concluded that
>> >     worktree-related maintenance functionality didn't belong in `git
>> >     prune`.
>> >
>> > Is that sufficient to clue in the reader that "checkout --to" is not
>> > final form,...
>>
>> Yeah, I think that is a good way to address my concern.
>>
>> The current draft release notes to 2.5 mentions this feature as
>> experimental and warns that its UI is bound to change.  We will
>> ship the upcoming release with "checkout --to" and the more places
>> we advise the users that this UI is not final, the better.
>
> Here it is in patch form. (I wouldn't be surprised if the non-ASCII
> characters in Duy's name in the context line get botched again...)

Ok, the following is merged:

https://github.com/git/git.github.io/pull/87

Thanks both,
Christian.