{"thread":{"id":"46860","subject":"[PATCH] clang-format: adjust line break penalties","startedAt":"2017-09-29T18:26:54Z","lastAt":"2017-10-03T01:08:23Z","messageCount":15,"participants":["Johannes Schindelin","Jonathan Nieder","Brandon Williams","Stephan Beyer","Junio C Hamano","Ramsay Jones"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"329184","messageId":"073f00fa11930a3607e34828e7563e1b2dc27d2a.1506709551.git.johannes.schindelin@gmx.de","threadId":"46860","inReplyTo":null,"subject":"[PATCH] clang-format: adjust line break penalties","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2017-09-29T18:26:44Z","receivedAt":"2017-09-29T18:26:54Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"We really, really, really want to limit the columns to 80 per line: One\nof the few consistent style comments on the Git mailing list is that the\nlines should not have more than 80 columns/line (even if 79 columns/line\nwould make more sense, given that the code is frequently viewed as diff,\nand diffs adding an extra character).\n\nThe penalty of 5 for excess characters is way too low to guarantee that,\nthough, as pointed out by Brandon Williams.\n\nFrom the existing clang-format examples and documentation, it appears\nthat 100 is a penalty deemed appropriate for Stuff You Really Don't\nWant, so let's assign that as the penalty for \"excess characters\", i.e.\noverly long lines.\n\nWhile at it, adjust the penalties further: we are actually not that keen\non preventing new line breaks within comments or string literals, so the\npenalty of 100 seems awfully high.\n\nLikewise, we are not all that adamant about keeping line breaks away\nfrom assignment operators (a lot of Git's code breaks immediately after\nthe `=` character just to keep that 80 columns/line limit).\n\nWe do frown a little bit more about functions' return types being on\ntheir own line than the penalty 0 would suggest, so this was adjusted,\ntoo.\n\nFinally, we do not particularly fancy breaking before the first parameter\nin a call, but if it keeps the line shorter than 80 columns/line, that's\nwhat we do, so lower the penalty for breaking before a call's first\nparameter, but not quite as much as introducing new line breaks to\ncomments.\n\nSigned-off-by: Johannes Schindelin \n---\nPublished-As: https://github.com/dscho/git/releases/tag/clang-format-column-limit-v1\nFetch-It-Via: git fetch https://github.com/dscho/git clang-format-column-limit-v1\n .clang-format | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/.clang-format b/.clang-format\nindex 3ede2628d2d..56822c116b1 100644\n--- a/.clang-format\n+++ b/.clang-format\n@@ -153,13 +153,13 @@ KeepEmptyLinesAtTheStartOfBlocks: false\n \n # Penalties\n # This decides what order things should be done if a line is too long\n-PenaltyBreakAssignment: 100\n-PenaltyBreakBeforeFirstCallParameter: 100\n-PenaltyBreakComment: 100\n+PenaltyBreakAssignment: 10\n+PenaltyBreakBeforeFirstCallParameter: 30\n+PenaltyBreakComment: 10\n PenaltyBreakFirstLessLess: 0\n-PenaltyBreakString: 100\n-PenaltyExcessCharacter: 5\n-PenaltyReturnTypeOnItsOwnLine: 0\n+PenaltyBreakString: 10\n+PenaltyExcessCharacter: 100\n+PenaltyReturnTypeOnItsOwnLine: 5\n \n # Don't sort #include's\n SortIncludes: false\n\nbase-commit: ea220ee40cbb03a63ebad2be902057bf742492fd\n-- \n2.14.2.windows.1\n"},{"id":"329186","messageId":"20170929184032.GK19555@aiede.mtv.corp.google.com","threadId":"46860","inReplyTo":"073f00fa11930a3607e34828e7563e1b2dc27d2a.1506709551.git.johannes.schindelin@gmx.de","subject":"Re: [PATCH] clang-format: adjust line break penalties","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-09-29T18:40:32Z","receivedAt":"2017-09-29T18:40:44Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi Dscho,\n\nJohannes Schindelin wrote:\n\n> Signed-off-by: Johannes Schindelin \n> ---\n> .clang-format | 12 ++++++------\n> 1 file changed, 6 insertions(+), 6 deletions(-)\n\nWell executed and well explained. Thank you.\n\nReviewed-by: Jonathan Nieder \n\nGoing forward, is there an easy way to preview the effect of this kind\nof change (e.g., to run \"make style\" on the entire codebase so as to be\nable to compare the result with two different versions of\n.clang-format)?\n\nThanks,\nJonathan\n"},{"id":"329191","messageId":"20170929195000.GE177031@google.com","threadId":"46860","inReplyTo":"20170929184032.GK19555@aiede.mtv.corp.google.com","subject":"Re: [PATCH] clang-format: adjust line break penalties","fromName":"Brandon Williams","fromEmail":"bmwill@google.com","sentAt":"2017-09-29T19:50:00Z","receivedAt":"2017-09-29T19:50:11Z","isPatch":true,"sender":{"key":"bwilliams.eng@gmail.com","avatar":null},"body":"On 09/29, Jonathan Nieder wrote:\n> Hi Dscho,\n> \n> Johannes Schindelin wrote:\n> \n> > Signed-off-by: Johannes Schindelin \n> > ---\n> > .clang-format | 12 ++++++------\n> > 1 file changed, 6 insertions(+), 6 deletions(-)\n> \n> Well executed and well explained. Thank you.\n> \n> Reviewed-by: Jonathan Nieder \n> \n> Going forward, is there an easy way to preview the effect of this kind\n> of change (e.g., to run \"make style\" on the entire codebase so as to be\n> able to compare the result with two different versions of\n> .clang-format)?\n> \n> Thanks,\n> Jonathan\n\nI don't think there's an easy way to do this yet (I'm sure we can make\none) though the biggest barrier to that is that most of the code base\nprobably isn't consistent with the current .clang-format.\n\nI also took a look at the patch and agree with all your points. I'm\nsure we'll still have to do some tweaking of these parameters but I'll\nstart using this locally and see if I find any problems.\n\n-- \nBrandon Williams\n"},{"id":"329221","messageId":"c1230d5b-ff84-8cf4-8ae7-b8387bf4bb04@gmx.net","threadId":"46860","inReplyTo":"20170929184032.GK19555@aiede.mtv.corp.google.com","subject":"Re: [PATCH] clang-format: adjust line break penalties","fromName":"Stephan Beyer","fromEmail":"s-beyer@gmx.net","sentAt":"2017-09-29T22:39:11Z","receivedAt":"2017-09-29T22:39:24Z","isPatch":true,"sender":{"key":"s-beyer@gmx.net","avatar":"https://avatars.githubusercontent.com/u/143889?v=4"},"body":"Hi,\n\nOn 09/29/2017 08:40 PM, Jonathan Nieder wrote:\n> Going forward, is there an easy way to preview the effect of this kind\n> of change (e.g., to run \"make style\" on the entire codebase so as to be\n> able to compare the result with two different versions of\n> .clang-format)?\n\nI just ran clang-format before and after the patch and pushed to github.\nThe resulting diff is quite big:\n\nhttps://github.com/sbeyer/git/commit/3d1186c4cf4dd7e40b97453af5fc1170f6868ccd\n\nCheers\nStephan\n\nPS: There should be a comment at the beginning of the .clang-format file\nthat says what version it is tested with (on my machine it worked with\n5.0 but not with 4.0) and there should also probably a remark that the\nclang-format-based style should only be understood as a hint or guidance\nand that most of the Git codebase does not conform it.\n"},{"id":"329222","messageId":"20170929224505.GN19555@aiede.mtv.corp.google.com","threadId":"46860","inReplyTo":"c1230d5b-ff84-8cf4-8ae7-b8387bf4bb04@gmx.net","subject":"Re: [PATCH] clang-format: adjust line break penalties","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-09-29T22:45:05Z","receivedAt":"2017-09-29T22:45:14Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Stephan Beyer wrote:\n> On 09/29/2017 08:40 PM, Jonathan Nieder wrote:\n\n>> Going forward, is there an easy way to preview the effect of this kind\n>> of change (e.g., to run \"make style\" on the entire codebase so as to be\n>> able to compare the result with two different versions of\n>> .clang-format)?\n>\n> I just ran clang-format before and after the patch and pushed to github.\n> The resulting diff is quite big:\n>\n> https://github.com/sbeyer/git/commit/3d1186c4cf4dd7e40b97453af5fc1170f6868ccd\n\nThanks. The first change I see there is\n\n -char *strbuf_realpath(struct strbuf *resolved, const char *path, int die_on_error)\n +char *\n +strbuf_realpath(struct strbuf *resolved, const char *path, int die_on_error)\n\nI understand why the line is broken, but the choice of line break is\nwrong. Seems like the penalty for putting return type on its own line\nquite high enough.\n\nMy Reviewed-by still stands, though. It gets \"make style\" to signal\nlong lines that should be broken, which is an improvement.\n\n> PS: There should be a comment at the beginning of the .clang-format file\n> that says what version it is tested with (on my machine it worked with\n> 5.0 but not with 4.0) and there should also probably a remark that the\n> clang-format-based style should only be understood as a hint or guidance\n> and that most of the Git codebase does not conform it.\n\nSounds good to me. Care to send it as a patch? :)\n\nThanks,\nJonathan\n"},{"id":"329258","messageId":"20170930213731.27133-1-s-beyer@gmx.net","threadId":"46860","inReplyTo":"20170929224505.GN19555@aiede.mtv.corp.google.com","subject":"[PATCH] Add a comment to .clang-format about the meaning of the file","fromName":"Stephan Beyer","fromEmail":"s-beyer@gmx.net","sentAt":"2017-09-30T21:37:31Z","receivedAt":"2017-09-30T21:41:52Z","isPatch":true,"sender":{"key":"s-beyer@gmx.net","avatar":"https://avatars.githubusercontent.com/u/143889?v=4"},"body":"Having a .clang-format file in a project can be understood in a way that code\nhas to be in the style defined by the .clang-format file, i.e., you just have\nto run clang-format over all code and you are set. This is not the case in the\nGit project, which is now reflected by an comment in the beginning of the file.\n\nAdditionally, the working clang-format version is mentioned because the config\ndirectives change from time to time (in a compatibility-breaking way).\n\nSigned-off-by: Stephan Beyer \n---\n\nNotes:\n On 09/30/2017 12:45 AM, Jonathan Nieder wrote:\n > Sounds good to me. Care to send it as a patch? :)\n \n Like this? :)\n\n .clang-format | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/.clang-format b/.clang-format\nindex 3ede2628d..558fc7fd8 100644\n--- a/.clang-format\n+++ b/.clang-format\n@@ -1,4 +1,8 @@\n-# Defaults\n+# This file is an example configuration for clang-format 5.0.\n+#\n+# Note that this style definition should only be understood as a hint\n+# for writing new code. Most of Git's codebase does not conform to\n+# this definition.\n \n # Use tabs whenever we need to fill whitespace that spans at least from one tab\n # stop to the next one.\n-- \n2.14.2.677.g5a59ab275\n\n"},{"id":"329268","messageId":"xmqq3773wpxj.fsf@gitster.mtv.corp.google.com","threadId":"46860","inReplyTo":"20170929184032.GK19555@aiede.mtv.corp.google.com","subject":"Re: [PATCH] clang-format: adjust line break penalties","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-01T02:40:56Z","receivedAt":"2017-10-01T02:41:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Hi Dscho,\n>\n> Johannes Schindelin wrote:\n>\n>> Signed-off-by: Johannes Schindelin \n>> ---\n>> .clang-format | 12 ++++++------\n>> 1 file changed, 6 insertions(+), 6 deletions(-)\n>\n> Well executed and well explained. Thank you.\n>\n> Reviewed-by: Jonathan Nieder \n\nThanks, both. I think the adjustment in the patch makes sense.\n\n"},{"id":"329269","messageId":"xmqqy3ovvb5q.fsf@gitster.mtv.corp.google.com","threadId":"46860","inReplyTo":"20170930213731.27133-1-s-beyer@gmx.net","subject":"Re: [PATCH] Add a comment to .clang-format about the meaning of the file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-01T02:45:21Z","receivedAt":"2017-10-01T02:45:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stephan Beyer writes:\n\n> Having a .clang-format file in a project can be understood in a way that code\n> has to be in the style defined by the .clang-format file, i.e., you just have\n> to run clang-format over all code and you are set. This is not the case in the\n> Git project, which is now reflected by an comment in the beginning of the file.\n>\n> Additionally, the working clang-format version is mentioned because the config\n> directives change from time to time (in a compatibility-breaking way).\n>\n> Signed-off-by: Stephan Beyer \n> ---\n>\n> Notes:\n> On 09/30/2017 12:45 AM, Jonathan Nieder wrote:\n> > Sounds good to me. Care to send it as a patch? :)\n> \n> Like this? :)\n>\n> .clang-format | 6 +++++-\n> 1 file changed, 5 insertions(+), 1 deletion(-)\n>\n> diff --git a/.clang-format b/.clang-format\n> index 3ede2628d..558fc7fd8 100644\n> --- a/.clang-format\n> +++ b/.clang-format\n> @@ -1,4 +1,8 @@\n> -# Defaults\n> +# This file is an example configuration for clang-format 5.0.\n> +#\n> +# Note that this style definition should only be understood as a hint\n> +# for writing new code. Most of Git's codebase does not conform to\n> +# this definition.\n\nI think this makes 50%-80% sense. As we have just seen in the patch\nthat started this thread, the rules currently in this file is known\nnot to be perfect (and I do not think the patch was meant to make,\nor claimed that it has made, the rules perfect---it was to fix the\nmost problematic part that was observed and is a good incremental\nimprovement), so we should treat it as such. \"does not conform to\"\ndoes not convey that--it makes as if a random patch to \"make it\nconform\" without thinking if the rules make sense were a welcome\naddition, which is absolutely the last signal we would want to send\nto the readers.\n"},{"id":"329303","messageId":"20171001154425.5568-1-s-beyer@gmx.net","threadId":"46860","inReplyTo":"20170929224505.GN19555@aiede.mtv.corp.google.com","subject":"[PATCH v2] Add a comment to .clang-format about the meaning of the file","fromName":"Stephan Beyer","fromEmail":"s-beyer@gmx.net","sentAt":"2017-10-01T15:44:25Z","receivedAt":"2017-10-01T15:44:39Z","isPatch":true,"sender":{"key":"s-beyer@gmx.net","avatar":"https://avatars.githubusercontent.com/u/143889?v=4"},"body":"Having a .clang-format file in a project can be understood in a way that code\nhas to be in the style defined by the .clang-format file, i.e., you just have\nto run clang-format over all code and you are set. This is not the case in the\nGit project, which is now reflected by a comment in the beginning of the file.\n\nAdditionally, the working clang-format version is mentioned because the config\ndirectives change from time to time (in a compatibility-breaking way).\n\nSigned-off-by: Stephan Beyer \n---\n\nNotes:\n On 10/01/2017 04:45 AM, Junio C Hamano wrote:\n > it makes as if a random patch to \"make it\n > conform\" without thinking if the rules make sense were a welcome\n > addition, which is absolutely the last signal we would want to send\n > to the readers.\n \n Right. I dropped that last sentence and replaced it by a sentence about human\n aesthetics judgement overruling mechanical rules -- I think that's somehow quoted\n from a comment of yours on the list.\n\n .clang-format | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/.clang-format b/.clang-format\nindex 3ede2628d..041b7be03 100644\n--- a/.clang-format\n+++ b/.clang-format\n@@ -1,4 +1,8 @@\n-# Defaults\n+# This file is an example configuration for clang-format 5.0.\n+#\n+# Note that this style definition should only be understood as a hint\n+# for writing new code. In the end, human aesthetics judgement overrules\n+# mechanical rules.\n \n # Use tabs whenever we need to fill whitespace that spans at least from one tab\n # stop to the next one.\n-- \n2.14.2.677.g5a59ab275\n\n"},{"id":"329317","messageId":"xmqq3772vce4.fsf@gitster.mtv.corp.google.com","threadId":"46860","inReplyTo":"20171001154425.5568-1-s-beyer@gmx.net","subject":"Re: [PATCH v2] Add a comment to .clang-format about the meaning of the file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-01T20:30:59Z","receivedAt":"2017-10-01T20:31:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stephan Beyer writes:\n\n> Having a .clang-format file in a project can be understood in a way that code\n> has to be in the style defined by the .clang-format file, i.e., you just have\n> to run clang-format over all code and you are set. This is not the case in the\n> Git project, which is now reflected by a comment in the beginning of the file.\n>\n> Additionally, the working clang-format version is mentioned because the config\n> directives change from time to time (in a compatibility-breaking way).\n>\n> Signed-off-by: Stephan Beyer \n> ---\n>\n> Notes:\n> On 10/01/2017 04:45 AM, Junio C Hamano wrote:\n> > it makes as if a random patch to \"make it\n> > conform\" without thinking if the rules make sense were a welcome\n> > addition, which is absolutely the last signal we would want to send\n> > to the readers.\n> \n> Right. I dropped that last sentence and replaced it by a sentence about human\n> aesthetics judgement overruling mechanical rules -- I think that's somehow quoted\n> from a comment of yours on the list.\n\nSorry, but that is not what I meant.\n\nI think we do want the endgame to be that .clang-format defines how\nthe code should look like. It's that we are not there yet, and I\nthink that is what we should say in this comment.\n\n\tNote that this style definition does not yet quite reflect\n\thow we want our code to look like, and adjusting the rules\n\tto match our style is still work in progress. Do not\n\tblindly adjust the style of _existing_ code, without\n\tchecking if the code is styled incorrectly, or the style\n\tdefinition in this file is still wrong.\n\nis what I should have suggested when writing my response.\n\n"},{"id":"329320","messageId":"5b7dabe3-fbc4-40fe-9d51-2c68c292f11d@gmx.net","threadId":"46860","inReplyTo":"xmqq3772vce4.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v2] Add a comment to .clang-format about the meaning of the file","fromName":"Stephan Beyer","fromEmail":"s-beyer@gmx.net","sentAt":"2017-10-01T21:29:23Z","receivedAt":"2017-10-01T21:29:37Z","isPatch":true,"sender":{"key":"s-beyer@gmx.net","avatar":"https://avatars.githubusercontent.com/u/143889?v=4"},"body":"On 10/01/2017 10:30 PM, Junio C Hamano wrote:\n> I think we do want the endgame to be that .clang-format defines how\n> the code should look like. It's that we are not there yet, and I\n> think that is what we should say in this comment.\n> \n> \tNote that this style definition does not yet quite reflect\n> \thow we want our code to look like, and adjusting the rules\n> \tto match our style is still work in progress. Do not\n> \tblindly adjust the style of _existing_ code, without\n> \tchecking if the code is styled incorrectly, or the style\n> \tdefinition in this file is still wrong.\n> \n> is what I should have suggested when writing my response.\nPretty long but okay. I tried to be shorter and more implicit (also\nbecause the CodingGuidelines are already pretty verbose on not changing\nexisting code style) and you're heading in the direction that there will\nbe some clang-format definition that matches the desired coding style (I\ndoubt that at least for the current clang-format versions, but that's\nanother topic).\n\nErm, so you're going to replace the comment? Or is it my task now to\nmake a v3 patch with your text? (The latter doesn't look useful to me...)\n\nStephan\n"},{"id":"329349","messageId":"xmqqpoa6tp79.fsf_-_@gitster.mtv.corp.google.com","threadId":"46860","inReplyTo":"20171001154425.5568-1-s-beyer@gmx.net","subject":"[PATCH v3] clang-format: add a comment about the meaning/status of the","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-01T23:37:14Z","receivedAt":"2017-10-01T23:37:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"From: Stephan Beyer \n\nHaving a .clang-format file in a project can be understood in a way that\ncode has to be in the style defined by the .clang-format file, i.e., you\njust have to run clang-format over all code and you are set.\n\nThis unfortunately is not yet the case in the Git project, as the\nformat file is still work in progress. Explain it with a comment in\nthe beginning of the file.\n\nAdditionally, the working clang-format version is mentioned because the\nconfig directives change from time to time (in a compatibility-breaking way).\n\nSigned-off-by: Stephan Beyer \nSigned-off-by: Junio C Hamano \n---\n\n * So here is a counter-proposal in a patch form. I agree that my\n earlier suggestion was unnecessarily verbose; this one spends\n just as many lines and not more than the v2 round of Stephan's\n patch.\n\n .clang-format | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/.clang-format b/.clang-format\nindex 56822c116b..7670eec8df 100644\n--- a/.clang-format\n+++ b/.clang-format\n@@ -1,4 +1,8 @@\n-# Defaults\n+# This file is an example configuration for clang-format 5.0.\n+#\n+# Note that this style definition should only be understood as a hint\n+# for writing new code. The rules are still work-in-progress and does\n+# not yet exactly match the style we have in the existing code.\n \n # Use tabs whenever we need to fill whitespace that spans at least from one tab\n # stop to the next one.\n-- \n2.14.2-820-gefeff4fbff\n\n"},{"id":"329464","messageId":"ce2267e3-21af-dbfc-5b20-45e272a775fb@gmx.net","threadId":"46860","inReplyTo":"xmqqpoa6tp79.fsf_-_@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3] clang-format: add a comment about the meaning/status of the","fromName":"Stephan Beyer","fromEmail":"s-beyer@gmx.net","sentAt":"2017-10-02T17:16:29Z","receivedAt":"2017-10-02T17:16:40Z","isPatch":true,"sender":{"key":"s-beyer@gmx.net","avatar":"https://avatars.githubusercontent.com/u/143889?v=4"},"body":"Hi,\n\nOn 10/02/2017 01:37 AM, Junio C Hamano wrote:\n> diff --git a/.clang-format b/.clang-format\n> index 56822c116b..7670eec8df 100644\n> --- a/.clang-format\n> +++ b/.clang-format\n> @@ -1,4 +1,8 @@\n> -# Defaults\n> +# This file is an example configuration for clang-format 5.0.\n> +#\n> +# Note that this style definition should only be understood as a hint\n> +# for writing new code. The rules are still work-in-progress and does\n> +# not yet exactly match the style we have in the existing code.\n\nI'm totally fine with this.\n\nStephan\n"},{"id":"329468","messageId":"20171002172135.GB5189@google.com","threadId":"46860","inReplyTo":"xmqqpoa6tp79.fsf_-_@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3] clang-format: add a comment about the meaning/status of the","fromName":"Brandon Williams","fromEmail":"bmwill@google.com","sentAt":"2017-10-02T17:21:35Z","receivedAt":"2017-10-02T17:21:45Z","isPatch":true,"sender":{"key":"bwilliams.eng@gmail.com","avatar":null},"body":"On 10/02, Junio C Hamano wrote:\n> From: Stephan Beyer \n> \n> Having a .clang-format file in a project can be understood in a way that\n> code has to be in the style defined by the .clang-format file, i.e., you\n> just have to run clang-format over all code and you are set.\n> \n> This unfortunately is not yet the case in the Git project, as the\n> format file is still work in progress. Explain it with a comment in\n> the beginning of the file.\n> \n> Additionally, the working clang-format version is mentioned because the\n> config directives change from time to time (in a compatibility-breaking way).\n> \n> Signed-off-by: Stephan Beyer \n> Signed-off-by: Junio C Hamano \n> ---\n> \n> * So here is a counter-proposal in a patch form. I agree that my\n> earlier suggestion was unnecessarily verbose; this one spends\n> just as many lines and not more than the v2 round of Stephan's\n> patch.\n> \n> .clang-format | 6 +++++-\n> 1 file changed, 5 insertions(+), 1 deletion(-)\n> \n> diff --git a/.clang-format b/.clang-format\n> index 56822c116b..7670eec8df 100644\n> --- a/.clang-format\n> +++ b/.clang-format\n> @@ -1,4 +1,8 @@\n> -# Defaults\n> +# This file is an example configuration for clang-format 5.0.\n> +#\n> +# Note that this style definition should only be understood as a hint\n> +# for writing new code. The rules are still work-in-progress and does\n> +# not yet exactly match the style we have in the existing code.\n\nThanks for writing up this header comment to the .clang-format file,\nit's something I definitely should have included when I introduced it.\n\nAnd I like the wording that you've both settled on, as it reflects our\nintentions (of having the code eventually conform to the format rules)\nand making note that this set of rules still needs to be tuned.\n\n\nThanks!\n\n> \n> # Use tabs whenever we need to fill whitespace that spans at least from one tab\n> # stop to the next one.\n> -- \n> 2.14.2-820-gefeff4fbff\n> \n\n-- \nBrandon Williams\n"},{"id":"329509","messageId":"57ab6f76-e150-26ab-3671-b14e0247a553@ramsayjones.plus.com","threadId":"46860","inReplyTo":"20171002172135.GB5189@google.com","subject":"Re: [PATCH v3] clang-format: add a comment about the meaning/status of the","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2017-10-03T01:08:13Z","receivedAt":"2017-10-03T01:08:23Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\n\nOn 02/10/17 18:21, Brandon Williams wrote:\n> On 10/02, Junio C Hamano wrote:\n>> From: Stephan Beyer \n>>\n>> Having a .clang-format file in a project can be understood in a way that\n>> code has to be in the style defined by the .clang-format file, i.e., you\n>> just have to run clang-format over all code and you are set.\n>>\n>> This unfortunately is not yet the case in the Git project, as the\n>> format file is still work in progress. Explain it with a comment in\n>> the beginning of the file.\n>>\n>> Additionally, the working clang-format version is mentioned because the\n>> config directives change from time to time (in a compatibility-breaking way).\n>>\n>> Signed-off-by: Stephan Beyer \n>> Signed-off-by: Junio C Hamano \n>> ---\n>>\n>> * So here is a counter-proposal in a patch form. I agree that my\n>> earlier suggestion was unnecessarily verbose; this one spends\n>> just as many lines and not more than the v2 round of Stephan's\n>> patch.\n>>\n>> .clang-format | 6 +++++-\n>> 1 file changed, 5 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/.clang-format b/.clang-format\n>> index 56822c116b..7670eec8df 100644\n>> --- a/.clang-format\n>> +++ b/.clang-format\n>> @@ -1,4 +1,8 @@\n>> -# Defaults\n>> +# This file is an example configuration for clang-format 5.0.\n>> +#\n>> +# Note that this style definition should only be understood as a hint\n>> +# for writing new code. The rules are still work-in-progress and does\n>> +# not yet exactly match the style we have in the existing code.\n> \n> Thanks for writing up this header comment to the .clang-format file,\n> it's something I definitely should have included when I introduced it.\n> \n> And I like the wording that you've both settled on, as it reflects our\n> intentions (of having the code eventually conform to the format rules)\n> and making note that this set of rules still needs to be tuned.\n\nJust for the record, I have 'clang-format version 3.8.0-2ubuntu4\n (tags/RELEASE_380/final)' on Linux Mint 18.2, which requires me\nto comment out:\n\n AlignEscapedNewlines: Left\n BreakStringLiterals: false\n PenaltyBreakAssignment: 100\n\nAnd on cygwin, I have 'clang-format version 4.0.1\n (tags/RELEASE_401/final)', which requires me to\ncomment out:\n\n AlignEscapedNewlines: Left\n PenaltyBreakAssignment: 100\n\nSo, I don't think I can play along! :(\n\n[When playing with 3.8 on Linux, I noted that clang-format\nseemed to ignore *all* settings in .clang-format, if it found\n*any* config that it didn't know about! Not very friendly. :-P ]\n\nATB,\nRamsay Jones\n\n"}]}