Re: [PATCH] doc: show usage of branch description

2015-09-15 Thread Philip Oakley 

From: "Junio C Hamano" 

"Philip Oakley"  writes:


It still means that my patch is incomplete in its aim to bring out
these possible broader usages.

I haven't yet looked at the mail archives to see if there is more
around the time of those introductions.


I guess this is largely my fault, but I think "git grep" is an
easier source of truth to work with than the list archive.

It eventually boils down to branch.*.description configuration and
all users of that would call read_branch_desc(), so if you check
callers of that helper function and see which commit introduced that
call for what purpose ("blame" is your friend), you would know how
they use the information under what condition.


$ git grep -n read_branch_desc -- \*.c
branch.c:143:int read_branch_desc(struct strbuf *buf, const char
*branch_name)
builtin/branch.c:771:   read_branch_desc(, branch_name);
builtin/fmt-merge-msg.c:211:if (!read_branch_desc(, name)) {
builtin/log.c:888:  read_branch_desc(, branch_name);

$ git blame -L210,212 -s builtin/fmt-merge-msg.c
898eacd8 210)
898eacd8 211)   if (!read_branch_desc(, name)) {
898eacd8 212)   const char *bp = desc.buf;

$ git show -s 898eacd8
commit 898eacd8ada2d012f977948350ed60845e238037
Author: Junio C Hamano 

[...]>

   Signed-off-by: Junio C Hamano 

etc. etc.


---
Thanks.
That was very useful seeing a few more of the options in combination.
That, combined with the updated G4W, is a lot better/faster.

I've also searched for:
$ git grep -n "\.description" -- \*.sh

which only came up with
git-request-pull.sh:74: ! git config "branch.$branch_name.description" 
>/dev/null

git-request-pull.sh:156: git config "branch.$branch_name.description"

as relevant hits:

Sometimes one can be a bit feart to try out some command options..

Philip

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: show usage of branch description

2015-09-15 Thread Philip Oakley 

From: "Junio C Hamano" 

"Philip Oakley"  writes:


It still means that my patch is incomplete in its aim to bring out
these possible broader usages.

I haven't yet looked at the mail archives to see if there is more
around the time of those introductions.


I guess this is largely my fault, but I think "git grep" is an
easier source of truth to work with than the list archive.

It eventually boils down to branch.*.description configuration and
all users of that would call read_branch_desc(), so if you check
callers of that helper function and see which commit introduced that
call for what purpose ("blame" is your friend), you would know how
they use the information under what condition.


$ git grep -n read_branch_desc -- \*.c
branch.c:143:int read_branch_desc(struct strbuf *buf, const char
*branch_name)
builtin/branch.c:771:   read_branch_desc(, branch_name);
builtin/fmt-merge-msg.c:211:if (!read_branch_desc(, name)) {
builtin/log.c:888:  read_branch_desc(, branch_name);

$ git blame -L210,212 -s builtin/fmt-merge-msg.c
898eacd8 210)
898eacd8 211)   if (!read_branch_desc(, name)) {
898eacd8 212)   const char *bp = desc.buf;

$ git show -s 898eacd8
commit 898eacd8ada2d012f977948350ed60845e238037
Author: Junio C Hamano 

[...]>

   Signed-off-by: Junio C Hamano 

etc. etc.


---
Thanks.
That was very useful seeing a few more of the options in combination.
That, combined with the updated G4W, is a lot better/faster.
Sometimes one can be a bit feart to try out some command options..


I've also searched for:

$ git grep -n "\.description" -- \*.sh

which only came up with

git-request-pull.sh:74: ! git config "branch.$branch_name.description" 
>/dev/null

git-request-pull.sh:156: git config "branch.$branch_name.description"

as relevant hits.

Philip

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: show usage of branch description

2015-09-14 Thread Philip Oakley 

From: "Jacob Keller" 

Hi,

On Sat, Sep 12, 2015 at 3:51 PM, Philip Oakley  
wrote:

The branch description will be included in 'git format-patch
--cover-letter' and in 'git pull-request' emails. Tell the reader.

While here, clarify that the description may be a multi-line
explanation of the purpose of the branch's patch series.

Signed-off-by: Philip Oakley 
---

This is a short doc patch to follow up $gmane/277628 where Johannes
Schindelin noted this otherwise undocumented feature.



Thanks for this.



 Documentation/git-branch.txt   | 3 ++-
 Documentation/git-format-patch.txt | 2 +-
 Documentation/git-request-pull.txt | 3 ++-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-branch.txt 
b/Documentation/git-branch.txt

index a67138a..79ad1c7 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -197,7 +197,8 @@ start-point is either a local or remote-tracking 
branch.


 --edit-description::
Open an editor and edit the text to explain what the branch 
is
-   for, to be used by various other commands (e.g. 
`request-pull`).
+   for, to be used by various other commands (e.g. 
`format-patch`

+   and `request-pull`). Multi-line explanations may be used.



Are these the only locations? Just want to make sure while we're 
updating it.


Searching for 'description' has many hits so it's not easy to be really 
sure. I had thought I'd asked an SO question ($SO/q/6866838) about 
branch descriptions many years ago, whose answers indicated it was 
little used, but actually I'd asked about the repo description (doh) 
which AFAICT is only used by gitweb.


A bit more delving found http://stackoverflow.com/a/8858853/717355 which 
suggests `git merge` would use it, but with no mention in the `git 
merge --help` man page. A link to the `git fmt-merge-msg` ("for internal 
use by scripts") finally provides the extra:


merge.branchdesc

In addition to branch names, populate the log message with the branch 
description text associated with them. Defaults to false.


However, that config key isn't listed in `git config --help` man page, 
so that capability is a bit buried. (note the default!)




It still means that my patch is incomplete in its aim to bring out these 
possible broader usages.



I haven't yet looked at the mail archives to see if there is more around 
the time of those introductions.




Otherwise, for what it's worth...

Acked-by: Jacob Keller 

For the future, it would also be nice to allow some use within `git 
branch` for a `--show[-full]-description` option such that when branch 
info is being given (-a, -l, etc), then the descriptions for the local 
branches (which may have descriptions) are displayed, either as a single 
first line, or as a full multi-line description. But that's coding & 
review for the future. 


--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: show usage of branch description

2015-09-14 Thread Philip Oakley 

From: "Philip Oakley" 

From: "Jacob Keller" 

Hi,

On Sat, Sep 12, 2015 at 3:51 PM, Philip Oakley  
wrote:

The branch description will be included in 'git format-patch
--cover-letter' and in 'git pull-request' emails. Tell the reader.

[...]
Are these the only locations? Just want to make sure while we're 
updating it.


A bit more delving found http://stackoverflow.com/a/8858853/717355 
which suggests `git merge` would use it, but with no mention in the 
`git merge --help` man page. A link to the `git fmt-merge-msg` ("for 
internal use by scripts") finally provides the extra:


merge.branchdesc

In addition to branch names, populate the log message with the branch 
description text associated with them. Defaults to false.


However, that config key isn't listed in `git config --help` man page, 
so that capability is a bit buried. (note the default!)


This is incorrect. It was fixed in fc0aa39 (Documentation: include 
'merge.branchdesc' for merge and config as well, 2015-05-27), but my 
local docs hadn't included it.




It still means that my patch is incomplete in its aim to bring out 
these possible broader usages.


i.e. mentioning 'merge' as a command that uses the branch description, 
and noting it within the merge pages.



--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: show usage of branch description

2015-09-14 Thread Junio C Hamano 
"Philip Oakley"  writes:

> It still means that my patch is incomplete in its aim to bring out
> these possible broader usages.
>
> I haven't yet looked at the mail archives to see if there is more
> around the time of those introductions.

I guess this is largely my fault, but I think "git grep" is an
easier source of truth to work with than the list archive.

It eventually boils down to branch.*.description configuration and
all users of that would call read_branch_desc(), so if you check
callers of that helper function and see which commit introduced that
call for what purpose ("blame" is your friend), you would know how
they use the information under what condition.


$ git grep -n read_branch_desc -- \*.c
branch.c:143:int read_branch_desc(struct strbuf *buf, const char *branch_name)
builtin/branch.c:771:   read_branch_desc(, branch_name);
builtin/fmt-merge-msg.c:211:if (!read_branch_desc(, name)) {
builtin/log.c:888:  read_branch_desc(, branch_name);

$ git blame -L210,212 -s builtin/fmt-merge-msg.c
898eacd8 210) 
898eacd8 211)   if (!read_branch_desc(, name)) {
898eacd8 212)   const char *bp = desc.buf;

$ git show -s 898eacd8
commit 898eacd8ada2d012f977948350ed60845e238037
Author: Junio C Hamano 
Date:   Thu Oct 6 23:12:09 2011 -0700

fmt-merge-msg: use branch.$name.description

This teaches "merge --log" and fmt-merge-msg to use branch description
information when merging a local topic branch into the mainline. The
description goes between the branch name label and the list of commit
titles.

The refactoring to share the common configuration parsing between
merge and fmt-merge-msg needs to be made into a separate patch.

Signed-off-by: Junio C Hamano 

etc. etc.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] doc: show usage of branch description

2015-09-12 Thread Philip Oakley 
The branch description will be included in 'git format-patch
--cover-letter' and in 'git pull-request' emails. Tell the reader.

While here, clarify that the description may be a multi-line
explanation of the purpose of the branch's patch series.

Signed-off-by: Philip Oakley 
---

This is a short doc patch to follow up $gmane/277628 where Johannes
Schindelin noted this otherwise undocumented feature.


 Documentation/git-branch.txt   | 3 ++-
 Documentation/git-format-patch.txt | 2 +-
 Documentation/git-request-pull.txt | 3 ++-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index a67138a..79ad1c7 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -197,7 +197,8 @@ start-point is either a local or remote-tracking branch.
 
 --edit-description::
Open an editor and edit the text to explain what the branch is
-   for, to be used by various other commands (e.g. `request-pull`).
+   for, to be used by various other commands (e.g. `format-patch`
+   and `request-pull`). Multi-line explanations may be used.
 
 --contains []::
Only list branches which contain the specified commit (HEAD
diff --git a/Documentation/git-format-patch.txt 
b/Documentation/git-format-patch.txt
index 0dac4e9..4035649 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -213,7 +213,7 @@ feeding the result to `git send-email`.
 
 --[no-]cover-letter::
In addition to the patches, generate a cover letter file
-   containing the shortlog and the overall diffstat.  You can
+   containing the branch description, shortlog and the overall diffstat.  
You can
fill in a description in the file before sending it out.
 
 --notes[=]::
diff --git a/Documentation/git-request-pull.txt 
b/Documentation/git-request-pull.txt
index 283577b..c32cb0b 100644
--- a/Documentation/git-request-pull.txt
+++ b/Documentation/git-request-pull.txt
@@ -14,7 +14,8 @@ DESCRIPTION
 ---
 
 Generate a request asking your upstream project to pull changes into
-their tree.  The request, printed to the standard output, summarizes
+their tree.  The request, printed to the standard output,
+begins with the branch description, summarizes
 the changes and indicates from where they can be pulled.
 
 The upstream project is expected to have the commit named by
-- 
2.4.2.windows.1.5.gd32afb6

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: show usage of branch description

2015-09-12 Thread Jacob Keller 
Hi,

On Sat, Sep 12, 2015 at 3:51 PM, Philip Oakley  wrote:
> The branch description will be included in 'git format-patch
> --cover-letter' and in 'git pull-request' emails. Tell the reader.
>
> While here, clarify that the description may be a multi-line
> explanation of the purpose of the branch's patch series.
>
> Signed-off-by: Philip Oakley 
> ---
>
> This is a short doc patch to follow up $gmane/277628 where Johannes
> Schindelin noted this otherwise undocumented feature.
>

Thanks for this.

>
>  Documentation/git-branch.txt   | 3 ++-
>  Documentation/git-format-patch.txt | 2 +-
>  Documentation/git-request-pull.txt | 3 ++-
>  3 files changed, 5 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index a67138a..79ad1c7 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -197,7 +197,8 @@ start-point is either a local or remote-tracking branch.
>
>  --edit-description::
> Open an editor and edit the text to explain what the branch is
> -   for, to be used by various other commands (e.g. `request-pull`).
> +   for, to be used by various other commands (e.g. `format-patch`
> +   and `request-pull`). Multi-line explanations may be used.
>

Are these the only locations? Just want to make sure while we're updating it.

Otherwise, for what it's worth...

Acked-by: Jacob Keller 

Regards,
Jake
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html