On 14 September 2012 04:06, Junio C Hamano <gitster@xxxxxxxxx> wrote:
> Andrew Ardill <andrew.ardill@xxxxxxxxx> writes:
>
>> Currently, the output for each branch looks something like:
>> * <branch-name> (<creation-date>) <number-of-commits>
>> (<merge-status>)
>> [list-of-commits]
>> (<branch-usage>)
>> <long-description>
>> <notes-and-memoranda>
>> <next-steps>
>>
>> and these are grouped by current integration status (new, graduated,
>> stalled etc)
>
> Yes. Thanks for a concise summary.
>
>> A format that would make this information easier for me to parse would
>> be something like:
>>
>> <short-branch-description>
>> <long-branch-description>
>> <notes>
>> <next-steps>
>> * <branch-name> (<creation-date>) <number-of-commits>
>> (<merge-status>)
>> [list-of-commits]
>> (<branch-usage>)
>
> I do not see how it makes any sense to have the "This is where the
> section begins with, and its name is this" line in the middle of a
> block indented in such a way. Care to explain?
I'm not quite sure what aspect you are referring to, so let me just
expand my reasoning a little bit and hopefully that clears things up.
First of all, I didn't spend that much time thinking through the
layout, merely re-arranged things so that what I considered most
important was at the start of each listing. I kept everything else the
same, with an extra level of indentation for everything except the
first line of each listing. Perhaps modifying the existing indentation
to better fit in this layout is in order, but that is in some ways
orthogonal to the ideas I was trying to present.
I am not against changing how each listing is laid out in a more
disruptive way, this was just a first attempt at making it easier to
parse.
I like the idea proposed by others to increase whitespace between
listings to make each stand out, however I think indentation is a
better method.
* Increased whitespace between listings lengthens the entire list,
requiring more scrolling and decreasing the amount of information on
each page. Simply indenting most lines by a few columns of whitespace
may cause some lines to wrap, but in general will not lengthen the
listing or decrease information density. [edit] I realised after
writing this that the addition of a <short-branch-description> does
actually increase the length of the listing, however it does not
decrease information density as much as a blank line.
* The visual difference between two blank lines and one is
significant, but not as distinct as the presence (or not) of a
character in the first column of text. In scanning a long document, I
propose that finding a line that starts in the first column of text is
easier than finding the next line which is preceded by two blank
lines. Similarly jumping forwards or backwards a listing would be
easier.
This is all a little academic though, so lets compare both versions
with an excerpt from the most recent "What's cooking"!
First, the extra blank line
-- >8 --
* jc/maint-blame-no-such-path (2012-09-10) 1 commit
- blame $path: avoid getting fooled by case insensitive filesystems
"git blame MAKEFILE" run in a history that has "Makefile" but not
"MAKEFILE" should say "No such file MAKEFILE in HEAD", but got
confused on a case insensitive filesystem.
* sl/autoconf (2012-09-11) 2 commits
- build: don't duplicate substitution of make variables
- build: improve GIT_CONF_SUBST signature
* cn/branch-set-upstream-to (2012-09-11) 2 commits
- completion: complete branch name for "branch --set-upstream-to="
- completion: add --set-upstream-to and --unset-upstream
Will merge to 'next'.
--------------------------------------------------
[Graduated to "master"]
* jc/maint-ident-missing-human-name (2012-08-31) 1 commit
(merged to 'next' on 2012-09-07 at 0e99b20)
+ split_ident_line(): make best effort when parsing author/committer line
"git show --format='%ci'" did not give timestamp correctly for
commits created without human readable name on "committer" line.
* jc/merge-bases (2012-08-31) 9 commits
(merged to 'next' on 2012-09-07 at ab0974d)
+ reduce_heads(): reimplement on top of remove_redundant()
+ merge-base: "--is-ancestor A B"
+ get_merge_bases_many(): walk from many tips in parallel
+ in_merge_bases(): use paint_down_to_common()
+ merge_bases_many(): split out the logic to paint history
+ in_merge_bases(): omit unnecessary redundant common ancestor reduction
+ http-push: use in_merge_bases() for fast-forward check
+ receive-pack: use in_merge_bases() for fast-forward check
+ in_merge_bases(): support only one "other" commit
Optimise the "merge-base" computation a bit, and also update its
users that do not need the full merge-base information to call a
cheaper subset.
-- 8< --
Now, the extra indentation and re-organised contents
-- >8 --
jc/maint-blame-no-such-path
"git blame MAKEFILE" run in a history that has "Makefile" but not
"MAKEFILE" should say "No such file MAKEFILE in HEAD", but got
confused on a case insensitive filesystem.
* jc/maint-blame-no-such-path (2012-09-10) 1 commit
- blame $path: avoid getting fooled by case insensitive filesystems
sl/autoconf
* sl/autoconf (2012-09-11) 2 commits
- build: don't duplicate substitution of make variables
- build: improve GIT_CONF_SUBST signature
cn/branch-set-upstream-to
Will merge to 'next'.
* cn/branch-set-upstream-to (2012-09-11) 2 commits
- completion: complete branch name for "branch --set-upstream-to="
- completion: add --set-upstream-to and --unset-upstream
--------------------------------------------------
[Graduated to "master"]
jc/maint-ident-missing-human-name
"git show --format='%ci'" did not give timestamp correctly for
commits created without human readable name on "committer" line.
* jc/maint-ident-missing-human-name (2012-08-31) 1 commit
(merged to 'next' on 2012-09-07 at 0e99b20)
+ split_ident_line(): make best effort when parsing author/committer line
jc/merge-bases
Optimise the "merge-base" computation a bit, and also update its
users that do not need the full merge-base information to call a
cheaper subset.
* jc/merge-bases (2012-08-31) 9 commits
(merged to 'next' on 2012-09-07 at ab0974d)
+ reduce_heads(): reimplement on top of remove_redundant()
+ merge-base: "--is-ancestor A B"
+ get_merge_bases_many(): walk from many tips in parallel
+ in_merge_bases(): use paint_down_to_common()
+ merge_bases_many(): split out the logic to paint history
+ in_merge_bases(): omit unnecessary redundant common ancestor reduction
+ http-push: use in_merge_bases() for fast-forward check
+ receive-pack: use in_merge_bases() for fast-forward check
+ in_merge_bases(): support only one "other" commit
-- 8< --
I personally find the second much more useful, but perhaps the
comparison will help other people evaluate them both.
>
> I can see some people may care more about the description than the
> list of commits [*1*], though.
>
>
> [Footnote]
>
> *1* It however is an indication that the title of each commit needs
> to be improved to convey enough information so that I do not have to
> write the branch description myself for them.
I remember something about including topic descriptions being
described when signed tag pull requests were being designed, could
that information potentially be coerced if available?
Regards,
Andrew Ardill
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html