threads / patch / 24556

patchSubmittingPatches: Cite the 50 char subject limit

Subject: [PATCH] SubmittingPatches: Cite the 50 char subject limit

## tl;dr

6 messages between Jul 28, 2010 and Jul 28, 2010. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

Ævar Arnfjörð Bjarmason· Jul 28, 2010, 14:11 UTC · lore

Change the SubmittingPatches recommendations to mention the 50 character soft limit on patch subject lines. 50 characters is the soft limit mentioned in git-commit(1) and gittutorial(7), it's also the point at which Gitweb, GitHub and various other Git front ends start abbreviating the commit message.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/SubmittingPatches |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)
Show changes to Documentation/SubmittingPatches +2 −1
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index eb53e06..099b238 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -7,7 +7,8 @@ Checklist (and a short version for the impatient):
 	  before committing
 	- do not check in commented out code or unneeded files
 	- the first line of the commit message should be a short
-	  description and should skip the full stop
+	  description (50 characters is the soft limit, see DISCUSSION
+	  in git-commit(1)), and should skip the full stop
 	- the body should provide a meaningful commit message, which:
 		- uses the imperative, present tense: "change",
 		  not "changed" or "changes".

-- 
1.7.0.4
Junio C Hamano· Jul 28, 2010, 17:23 UTC · re: Ævar Arnfjörð Bjarmason · lore

Re: [PATCH] SubmittingPatches: Cite the 50 char subject limit

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
Show 5 quoted lines
> Change the SubmittingPatches recommendations to mention the 50
> character soft limit on patch subject lines. 50 characters is the soft
> limit mentioned in git-commit(1) and gittutorial(7), it's also the
> point at which Gitweb, GitHub and various other Git front ends start
> abbreviating the commit message.

Hmph, we probably would want to do s/50 character/&s/ in the two manual pages. I do not think if anybody is ready to stand behind the specific number "50", and we can bikeshed about it separately.

The spirit of having a soft limit is twofold:
 - It should fit on "git log --oneline" comfortably;
 - If your change is too complex to be summarized in such a short
   sentence, you probably are doing too many things in one commit.

The first does not justify "50" any better than other arbitrary limit, but with things like --graph and --source, anything longer makes the resulting output very close to the edge of an 80-column terminal.

The second does not justify "50" either, as your language may be verbose or terse (e.g. Japanese can cram far more information in a 140-char tweet than somebody writing in English), but it is a more important one between the two rationales above.

Ævar Arnfjörð Bjarmason· Jul 28, 2010, 19:25 UTC · re: Junio C Hamano · lore

Re: [PATCH] SubmittingPatches: Cite the 50 char subject limit

On Wed, Jul 28, 2010 at 17:23, Junio C Hamano <gitster@pobox.com> wrote:
Show 10 quoted lines
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> Change the SubmittingPatches recommendations to mention the 50
>> character soft limit on patch subject lines. 50 characters is the soft
>> limit mentioned in git-commit(1) and gittutorial(7), it's also the
>> point at which Gitweb, GitHub and various other Git front ends start
>> abbreviating the commit message.
>
> Hmph, we probably would want to do s/50 character/&s/ in the two manual
> pages.

I'm not sure if "with a single short (less than 50 character) line" is is grammatically correct with "characters", since "characters line" wouldn't make sense.

On the other hand that sentence violates the rule that when you put something in parens your sentence should still make sense with s/[()]//g, "a single short less than 50 character line" is pushing it.

I do not think if anybody is ready to stand behind the specific
Show 17 quoted lines
> number "50", and we can bikeshed about it separately.
>
> The spirit of having a soft limit is twofold:
>
>  - It should fit on "git log --oneline" comfortably;
>
>  - If your change is too complex to be summarized in such a short
>   sentence, you probably are doing too many things in one commit.
>
> The first does not justify "50" any better than other arbitrary limit, but
> with things like --graph and --source, anything longer makes the resulting
> output very close to the edge of an 80-column terminal.
>
> The second does not justify "50" either, as your language may be verbose
> or terse (e.g. Japanese can cram far more information in a 140-char tweet
> than somebody writing in English), but it is a more important one between
> the two rationales above.

Right, 50 characters isn't magical. But I find it to be a really good indicator that I'm going over the limit.

When I want to write something that's 60 characters or more that's usually a sign that I should simplify the subject and just write a more detailed body.

50 also fits neatly into interfaces where you want the summary and 2-3 other things on the page. Like in the Gitweb or Github interfaces.

Joshua Juran· Jul 28, 2010, 19:49 UTC · re: Ævar Arnfjörð Bjarmason · lore

Re: [PATCH] SubmittingPatches: Cite the 50 char subject limit

On Jul 28, 2010, at 12:25 PM, Ævar Arnfjörð Bjarmason wrote:
Show 14 quoted lines
> On Wed, Jul 28, 2010 at 17:23, Junio C Hamano <gitster@pobox.com>  
> wrote:
>
>> Hmph, we probably would want to do s/50 character/&s/ in the two  
>> manual
>> pages.
>
> I'm not sure if "with a single short (less than 50 character) line" is
> is grammatically correct with "characters", since "characters line"
> wouldn't make sense.
>
> On the other hand that sentence violates the rule that when you put
> something in parens your sentence should still make sense with
> s/[()]//g, "a single short less than 50 character line" is pushing it.

If the number of characters is less than 50, then there are fewer than 50 characters.

This is a short line of fewer than 50 characters.

Cheers, Josh

Ævar Arnfjörð Bjarmason· Jul 28, 2010, 20:15 UTC · re: Joshua Juran · lore

Re: [PATCH] SubmittingPatches: Cite the 50 char subject limit

On Wed, Jul 28, 2010 at 19:49, Joshua Juran <jjuran@gmail.com> wrote:
Show 19 quoted lines
> On Jul 28, 2010, at 12:25 PM, Ævar Arnfjörð Bjarmason wrote:
>
>> On Wed, Jul 28, 2010 at 17:23, Junio C Hamano <gitster@pobox.com> wrote:
>>
>>> Hmph, we probably would want to do s/50 character/&s/ in the two manual
>>> pages.
>>
>> I'm not sure if "with a single short (less than 50 character) line" is
>> is grammatically correct with "characters", since "characters line"
>> wouldn't make sense.
>>
>> On the other hand that sentence violates the rule that when you put
>> something in parens your sentence should still make sense with
>> s/[()]//g, "a single short less than 50 character line" is pushing it.
>
> If the number of characters is less than 50, then there are fewer than 50
> characters.
>
> This is a short line of fewer than 50 characters.

I don't understand the context of that remark or what you're replying to.

I meant that I found the "single short (less than 50 character) line" bit in git-commit.txt, gittutorial.txt and user-manual.txt odd to read.

What did you mean?
Joshua Juran· Jul 28, 2010, 20:32 UTC · re: Ævar Arnfjörð Bjarmason · lore

Re: [PATCH] SubmittingPatches: Cite the 50 char subject limit

On Jul 28, 2010, at 1:15 PM, Ævar Arnfjörð Bjarmason wrote:
Show 23 quoted lines
> On Wed, Jul 28, 2010 at 19:49, Joshua Juran <jjuran@gmail.com> wrote:
>> On Jul 28, 2010, at 12:25 PM, Ævar Arnfjörð Bjarmason wrote:
>>
>>> On Wed, Jul 28, 2010 at 17:23, Junio C Hamano <gitster@pobox.com>  
>>> wrote:
>>>
>>>> Hmph, we probably would want to do s/50 character/&s/ in the two  
>>>> manual
>>>> pages.
>>>
>>> I'm not sure if "with a single short (less than 50 character)  
>>> line" is
>>> is grammatically correct with "characters", since "characters line"
>>> wouldn't make sense.
>>>
>>> On the other hand that sentence violates the rule that when you put
>>> something in parens your sentence should still make sense with
>>> s/[()]//g, "a single short less than 50 character line" is pushing  
>>> it.
>>
>> If the number of characters is less than 50, then there are fewer  
>> than 50
>> characters.

This demonstrates the distinction between "less" and "fewer". Intensities (like raw numbers) and mass quantities are less; discrete objects are fewer.

>> This is a short line of fewer than 50 characters.

This demonstrates a grammatically correct way of phrasing a constraint on line length. I could have put the latter half in parentheses, but then it wouldn't be true. :-)

Show 6 quoted lines
> I don't understand the context of that remark or what you're replying
> to.
>
> I meant that I found the "single short (less than 50 character) line"
> bit in git-commit.txt, gittutorial.txt and user-manual.txt odd to
> read.
Agreed.
> What did you mean?

See above. You could also use "50-character" as an adjective, but "single short line (of fewer than 50 characters)" may be more easily parsed. Another option is "single short line (shorter than 50 characters)". I find it less stilted without "of fewer", but the repetition of "short" is a little clumsy.

Josh

← back to recent threads