[PATCH] editorconfig: Add automatic editor configuration file

[PATCH] editorconfig: Add automatic editor configuration file

[Danny Lin]

EditorConfig is a standard for defining basic editor configuration in
projects. There is support available for 47 code editors as of writing,
including both built-in and extension support. Many notable projects
have adopted the standard already, including zsh, htop, and qemu.

While this isn't a full-fledged C code style specifier, it does set some
basic ground rules that make it more convenient for contributors to use
any editor of their choice and not have to worry about indentation, line
endings, encoding, final newlines, etc. This should make it
significantly easier to conform to the kernel's general code style when
used in combination with clang-format.

For more information, check the official EditorConfig website:
https://editorconfig.org/

Signed-off-by: Danny Lin <danny@kdrag0n.dev>
---
 .editorconfig                      | 16 ++++++++++++++++
 .gitignore                         |  1 +
 Documentation/process/4.Coding.rst |  6 ++++++
 3 files changed, 23 insertions(+)
 create mode 100644 .editorconfig

diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 000000000000..580d2e90d855
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: GPL-2.0
+# Linux kernel EditorConfig file (https://editorconfig.org/)
+
+# Located at the project root
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+
+indent_style = tab
+indent_size = 8
+
+# This avoids introducing too many unnecessary changes in trivial commits
+trim_trailing_whitespace = false
diff --git a/.gitignore b/.gitignore
index 87b9dd8a163b..956bcc3c9d76 100644
--- a/.gitignore
+++ b/.gitignore
@@ -89,6 +89,7 @@ modules.order
 #
 !.clang-format
 !.cocciconfig
+!.editorconfig
 !.get_maintainer.ignore
 !.gitattributes
 !.gitignore
diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst
index 13dd893c9f88..c5c46bcafdad 100644
--- a/Documentation/process/4.Coding.rst
+++ b/Documentation/process/4.Coding.rst
@@ -66,6 +66,12 @@ for aligning variables/macros, for reflowing text and other similar tasks.
 See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
 for more details.
 
+Some basic editor settings, such as indentation and line endings, will be
+set automatically if you are using an editor that is compatible with
+EditorConfig. See the official EditorConfig website for more information: 
+
+https://editorconfig.org/
+
 
 Abstraction layers
 ******************
-- 
2.27.0

Re: [PATCH] editorconfig: Add automatic editor configuration file

[Miguel Ojeda]

Hi Danny,

On Fri, Jul 3, 2020 at 2:16 AM Danny Lin <danny@kdrag0n.dev> wrote:
>
> +[*]
> +charset = utf-8
> +end_of_line = lf

While UTF-8 and LF are probably OK for all files, I am not 100% sure about:

> +insert_final_newline = true
> +indent_style = tab
> +indent_size = 8

for other languages and non-code files we may have around. Perhaps it
is best to avoid `[*]` unless we are sure?

Cheers,
Miguel

Re: [PATCH] editorconfig: Add automatic editor configuration file

[Danny Lin]

On Thursday, July 2, 2020 at 10:38 PM, Miguel Ojeda wrote:
> Hi Danny,
> 
> On Fri, Jul 3, 2020 at 2:16 AM Danny Lin <danny@kdrag0n.dev> wrote:
> > +[*]
> > +charset = utf-8
> > +end_of_line = lf
> 
> While UTF-8 and LF are probably OK for all files, I am not 100% sure 
about:
> > +insert_final_newline = true
> > +indent_style = tab
> > +indent_size = 8
> 
> for other languages and non-code files we may have around. Perhaps it
> is best to avoid `[*]` unless we are sure?

Most of the other exceptions can be accomodated for with more specific 
rules below the base [*] section. I just went through most of the 
kernel's files and added rules for the vast majority of the exceptinos 
to the 8-column tab indent style, though there are still some that 
haven't been covered.

It looks like some types of files lack consistent indentation, e.g. 
arch/mips/*/Platform and some shell scripts in scripts/ tools/testing/
selftests/ftrace/test.d/kprobe/*.tc. There are also some files that were 
highly inconsistent even within themselves (e.g. drivers/gpu/drm/amd/
amdkfd/cwsr_trap_handler_gfx*.asm), so setting indentation settings to 
something sane by default doesn't make them any worse. After all, no 
automated code style tooling is perfect and there will be edge cases 
where it breaks down.

That being said, I think most of the exceptions should be taken care of 
now; please feel free to suggest a better way to deal with these.

> 
> Cheers,
> Miguel

[PATCH v2] editorconfig: Add automatic editor configuration file

[Danny Lin]

EditorConfig is a standard for defining basic editor configuration in
projects. There is support available for 47 code editors as of writing,
including both built-in and extension support. Many notable projects
have adopted the standard already, including zsh, htop, and qemu.

While this isn't a full-fledged C code style specifier, it does set some
basic ground rules that make it more convenient for contributors to use
any editor of their choice and not have to worry about indentation, line
endings, encoding, final newlines, etc. This should make it
significantly easier to conform to the kernel's general code style when
used in combination with clang-format.

For more information, check the official EditorConfig website:
https://editorconfig.org/

Signed-off-by: Danny Lin <danny@kdrag0n.dev>
---
v2:
  - Added rules for most exceptions to the 8-column tab indent style

 .editorconfig                      | 37 ++++++++++++++++++++++++++++++
 .gitignore                         |  1 +
 Documentation/process/4.Coding.rst |  6 +++++
 3 files changed, 44 insertions(+)
 create mode 100644 .editorconfig

diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 000000000000..ab886ff0f66e
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: GPL-2.0
+# Linux kernel EditorConfig file (https://editorconfig.org/)
+
+# Located at the project root
+root = true
+
+# Base settings for most files
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+
+indent_style = tab
+indent_size = 8
+
+# This avoids introducing too many unnecessary changes in trivial commits
+trim_trailing_whitespace = false
+
+# General 4-space files
+[*.{pl,pm,py,tc,json,tc}]
+indent_style = space
+indent_size = 4
+
+# General 2-space files
+[*.{rb,rst,yaml,cocci,xsl,svg,bconf,clang-format}]
+indent_style = space
+indent_size = 2
+
+# Perf script wrappers
+[tools/perf/scripts/*/bin/*]
+indent_style = space
+indent_size = 4
+
+# Man pages
+[*.{1,2,3,4,5,6,7,8}]
+indent_style = space
+indent_size = 2
diff --git a/.gitignore b/.gitignore
index 87b9dd8a163b..956bcc3c9d76 100644
--- a/.gitignore
+++ b/.gitignore
@@ -89,6 +89,7 @@ modules.order
 #
 !.clang-format
 !.cocciconfig
+!.editorconfig
 !.get_maintainer.ignore
 !.gitattributes
 !.gitignore
diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst
index 13dd893c9f88..25b39dc8751d 100644
--- a/Documentation/process/4.Coding.rst
+++ b/Documentation/process/4.Coding.rst
@@ -66,6 +66,12 @@ for aligning variables/macros, for reflowing text and other similar tasks.
 See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
 for more details.
 
+Some basic editor settings, such as indentation and line endings, will be
+set automatically if you are using an editor that is compatible with
+EditorConfig. See the official EditorConfig website for more information:
+
+https://editorconfig.org/
+
 
 Abstraction layers
 ******************
-- 
2.27.0

Re: [PATCH v2] editorconfig: Add automatic editor configuration file

[Jonathan Corbet]

On Fri,  3 Jul 2020 00:31:43 -0700
Danny Lin <danny@kdrag0n.dev> wrote:

> EditorConfig is a standard for defining basic editor configuration in
> projects. There is support available for 47 code editors as of writing,
> including both built-in and extension support. Many notable projects
> have adopted the standard already, including zsh, htop, and qemu.
> 
> While this isn't a full-fledged C code style specifier, it does set some
> basic ground rules that make it more convenient for contributors to use
> any editor of their choice and not have to worry about indentation, line
> endings, encoding, final newlines, etc. This should make it
> significantly easier to conform to the kernel's general code style when
> used in combination with clang-format.
> 
> For more information, check the official EditorConfig website:
> https://editorconfig.org/
> 
> Signed-off-by: Danny Lin <danny@kdrag0n.dev>
> ---

So I worry a bit that not everybody will welcome the addition of a dotfile
that may be magically interpreted by their editor.  I also worry that the
file itself could become a battleground for people wanting to argue about
style issues.

Perhaps I worry a bit too much...?

jon

Re: [PATCH v2] editorconfig: Add automatic editor configuration file

[Rasmus Villemoes]

On 03/07/2020 14.29, Jonathan Corbet wrote:

[doing a bit of necromancy here]

> On Fri,  3 Jul 2020 00:31:43 -0700
> Danny Lin <danny@kdrag0n.dev> wrote:
> 
>> EditorConfig is a standard for defining basic editor configuration in
>> projects. There is support available for 47 code editors as of writing,
>> including both built-in and extension support. Many notable projects
>> have adopted the standard already, including zsh, htop, and qemu.
>>
>> While this isn't a full-fledged C code style specifier, it does set some
>> basic ground rules that make it more convenient for contributors to use
>> any editor of their choice and not have to worry about indentation, line
>> endings, encoding, final newlines, etc. This should make it
>> significantly easier to conform to the kernel's general code style when
>> used in combination with clang-format.
>>
>> For more information, check the official EditorConfig website:
>> https://editorconfig.org/
>>
>> Signed-off-by: Danny Lin <danny@kdrag0n.dev>
>> ---
> 
> So I worry a bit that not everybody will welcome the addition of a dotfile
> that may be magically interpreted by their editor.

I would suppose that one would have to enable editorconfig support
explicitly in one's editor, so this would have no effect for people that
haven't done so (though there are almost certainly exceptions).

> I also worry that the
> file itself could become a battleground for people wanting to argue about
> style issues.

I don't think so, not any more than the coding-style document is, and
that seems to be pretty solid (but as doc maintainer, you'd know better).

> 
> Perhaps I worry a bit too much...?

As someone who regularly needs to submit patches to random upstream
projects to fix bugs or implement minor features, I for one would really
welcome more widespread use of editorconfig. While I mostly work with
the linux kernel (and other projects using the same C style), so my
default C style setting is "linux", even for the kernel this would be
helpful to me when I poke around in none-C files (shell scripts, for
example).

Rasmus

Re: [PATCH v2] editorconfig: Add automatic editor configuration file

[Masahiro Yamada]

On Wed, Mar 24, 2021 at 8:01 PM Rasmus Villemoes
<linux@rasmusvillemoes.dk> wrote:
>
> On 03/07/2020 14.29, Jonathan Corbet wrote:
>
> [doing a bit of necromancy here]
>
> > On Fri,  3 Jul 2020 00:31:43 -0700
> > Danny Lin <danny@kdrag0n.dev> wrote:
> >
> >> EditorConfig is a standard for defining basic editor configuration in
> >> projects. There is support available for 47 code editors as of writing,
> >> including both built-in and extension support. Many notable projects
> >> have adopted the standard already, including zsh, htop, and qemu.
> >>
> >> While this isn't a full-fledged C code style specifier, it does set some
> >> basic ground rules that make it more convenient for contributors to use
> >> any editor of their choice and not have to worry about indentation, line
> >> endings, encoding, final newlines, etc. This should make it
> >> significantly easier to conform to the kernel's general code style when
> >> used in combination with clang-format.
> >>
> >> For more information, check the official EditorConfig website:
> >> https://editorconfig.org/
> >>
> >> Signed-off-by: Danny Lin <danny@kdrag0n.dev>
> >> ---
> >
> > So I worry a bit that not everybody will welcome the addition of a dotfile
> > that may be magically interpreted by their editor.
>
> I would suppose that one would have to enable editorconfig support
> explicitly in one's editor, so this would have no effect for people that
> haven't done so (though there are almost certainly exceptions).
>
> > I also worry that the
> > file itself could become a battleground for people wanting to argue about
> > style issues.
>
> I don't think so, not any more than the coding-style document is, and
> that seems to be pretty solid (but as doc maintainer, you'd know better).
>
> >
> > Perhaps I worry a bit too much...?
>
> As someone who regularly needs to submit patches to random upstream
> projects to fix bugs or implement minor features, I for one would really
> welcome more widespread use of editorconfig. While I mostly work with
> the linux kernel (and other projects using the same C style), so my
> default C style setting is "linux", even for the kernel this would be
> helpful to me when I poke around in none-C files (shell scripts, for
> example).
>
> Rasmus


Just from my curiosity, I just checked the behavior
when the language is specified by a shebang line.

For example, scripts/diffconfig has no file suffix,
but specifies '#!/usr/bin/env python3'
at the very top line.
This is sensible for tools that interface to users.
Users have no interest in which language is used
internally.


As far as I test this patch on Emacs, it follows the rule
of [*] rather than [*.{pl,pm,py,tc,json,tc}].

This is the correct behavior but not what we want in general.

I do not mean I am negative to this patch.
Rather, I very much like this patch, but I just
wondered how this case could be handled.

I found this:
https://github.com/editorconfig/editorconfig/issues/404
I did not read through it, though.


--
Best Regards
Masahiro Yamada

Re: [PATCH v2] editorconfig: Add automatic editor configuration file

[Miguel Ojeda]

On Thu, Mar 25, 2021 at 8:02 AM Masahiro Yamada <masahiroy@kernel.org> wrote:
>
> This is sensible for tools that interface to users.
> Users have no interest in which language is used
> internally.

Agreed in the general case (e.g. everyday tools). In the kernel's
case, however, I think it is not as important.

And I guess most of us tab-autocomplete anyway... :-)

> Rather, I very much like this patch, but I just
> wondered how this case could be handled.

Symlinks might be a good way when there is an installer of some kind.
But in the kernel's case, I would prefer to avoid having symlinks for
every script (in particular if they are in the same folder).

Cheers,
Miguel

Re: [PATCH v2] editorconfig: Add automatic editor configuration file

[Matthew Wilcox]

On Fri, Jul 03, 2020 at 12:31:43AM -0700, Danny Lin wrote:
> +# This avoids introducing too many unnecessary changes in trivial commits
> +trim_trailing_whitespace = false

I think we prefer trailing whitespace to be trimmed, even for trivial commits.

> +# General 4-space files
> +[*.{pl,pm,py,tc,json,tc}]
> +indent_style = space
> +indent_size = 4
> +
> +# General 2-space files
> +[*.{rb,rst,yaml,cocci,xsl,svg,bconf,clang-format}]
> +indent_style = space
> +indent_size = 2

The rst files I've seen either use tabs or three spaces for indent.
Where did this 2 come from?

Re: [PATCH v2] editorconfig: Add automatic editor configuration file

[Joe Perches]

On Fri, 2020-07-03 at 13:49 +0100, Matthew Wilcox wrote:
> On Fri, Jul 03, 2020 at 12:31:43AM -0700, Danny Lin wrote:
> > +# This avoids introducing too many unnecessary changes in trivial commits
> > +trim_trailing_whitespace = false
> 
> I think we prefer trailing whitespace to be trimmed, even for trivial commits.

I think so as well, but I also believe the flag will
whitespace trim not just any modified lines in a patch,
but all lines in the file.

That _might_ be an issue, but if it is, it's trivial.

There are ~50k files and ~26000k lines in the linux
kernel source tree.

There are ~2k files and ~24k lines with trailing
spaces in the code.

$ git grep -P --name-only "\s+$" -- '*.[ch]' | wc -l
2035

$ git grep -P "\s+$" -- '*.[ch]' | wc -l
24083

It's spread all over the kernel, mostly in old files
so likely it doesn't matter much.

$ git grep -P --name-only "\s+$" -- '*.[ch]' | \
  cut -f1,2 -d'/' | sort | uniq -c
    108 arch/alpha
     51 arch/arm
      1 arch/arm64
     18 arch/ia64
     20 arch/m68k
      1 arch/mips
     90 arch/parisc
     73 arch/powerpc
     20 arch/s390
      2 arch/sh
     57 arch/sparc
     32 arch/um
     27 arch/x86
     17 arch/xtensa
      1 block/blk-mq.h
      7 block/partitions
      1 block/scsi_ioctl.c
      1 crypto/khazad.c
      1 crypto/md4.c
      1 crypto/md5.c
      1 crypto/proc.c
      1 crypto/tea.c
      1 crypto/tgr192.c
      1 crypto/twofish_generic.c
      4 drivers/acpi
      1 drivers/ata
     29 drivers/atm
      1 drivers/base
     31 drivers/block
      1 drivers/bus
      1 drivers/cdrom
     20 drivers/char
      2 drivers/clk
      3 drivers/clocksource
      1 drivers/connector
      2 drivers/cpufreq
      1 drivers/cpuidle
      1 drivers/crypto
      1 drivers/dio
      1 drivers/dma
      1 drivers/dma-buf
      1 drivers/extcon
     55 drivers/gpu
      8 drivers/hid
      3 drivers/hwmon
      5 drivers/i2c
     18 drivers/ide
      3 drivers/iio
      1 drivers/infiniband
      6 drivers/input
      1 drivers/irqchip
     14 drivers/macintosh
      1 drivers/memory
      2 drivers/message
      1 drivers/mfd
      1 drivers/misc
      2 drivers/mmc
      7 drivers/mtd
     85 drivers/net
      3 drivers/nvme
     17 drivers/parisc
     10 drivers/parport
     13 drivers/pcmcia
      2 drivers/platform
      2 drivers/pnp
      1 drivers/power
      1 drivers/regulator
     10 drivers/s390
      4 drivers/sbus
    121 drivers/scsi
      2 drivers/soc
      1 drivers/spi
      1 drivers/staging
      1 drivers/target
     30 drivers/tty
     31 drivers/usb
      1 drivers/vhost
     70 drivers/video
      2 drivers/xen
      2 fs/adfs
      1 fs/affs
      1 fs/afs
      1 fs/aio.c
      1 fs/bad_inode.c
      1 fs/bfs
      1 fs/binfmt_aout.c
      1 fs/binfmt_elf.c
      1 fs/binfmt_em86.c
      1 fs/block_dev.c
      3 fs/btrfs
      1 fs/buffer.c
      2 fs/ceph
      2 fs/cifs
     11 fs/coda
      1 fs/compat.c
      1 fs/dcache.c
      1 fs/dcookies.c
      1 fs/direct-io.c
      3 fs/dlm
      1 fs/d_path.c
      5 fs/efs
      9 fs/ext2
      4 fs/ext4
      1 fs/fcntl.c
      1 fs/filesystems.c
      9 fs/freevxfs
      1 fs/fscache
     13 fs/gfs2
      1 fs/hfs
     11 fs/hpfs
      4 fs/isofs
      3 fs/jbd2
      9 fs/jffs2
      5 fs/lockd
      1 fs/mpage.c
      1 fs/namei.c
     11 fs/nfs
     16 fs/nfsd
     37 fs/nls
      8 fs/ntfs
      4 fs/ocfs2
      1 fs/omfs
      1 fs/open.c
      1 fs/openpromfs
      1 fs/pnode.c
      1 fs/posix_acl.c
      5 fs/proc
      1 fs/qnx4
      1 fs/readdir.c
      1 fs/read_write.c
      2 fs/reiserfs
      1 fs/select.c
      5 fs/sysv
      1 fs/timerfd.c
      1 fs/ubifs
      9 fs/ufs
      9 fs/xfs
      8 include/crypto
     97 include/linux
      6 include/math-emu
     29 include/net
      8 include/scsi
     22 include/sound
      1 include/trace
    114 include/uapi
      6 include/video
      2 include/xen
      1 init/do_mounts.c
      1 kernel/audit.h
      1 kernel/auditsc.c
      1 kernel/nsproxy.c
      1 kernel/power
      1 kernel/signal.c
      1 kernel/sysctl.c
      3 kernel/trace
      1 kernel/user.c
      2 lib/fonts
      1 lib/inflate.c
      1 lib/libcrc32c.c
      1 lib/textsearch.c
      1 lib/ts_bm.c
      1 lib/ts_kmp.c
      3 lib/zlib_deflate
      2 lib/zlib_inflate
      1 mm/memory-failure.c
      1 mm/oom_kill.c
      1 mm/page_io.c
      1 mm/rmap.c
      1 mm/swap_state.c
      1 net/ethtool
      1 net/rxrpc
      1 samples/connector
      1 scripts/asn1_compiler.c
      1 scripts/gcc-plugins
      1 security/commoncap.c
      1 security/device_cgroup.c
      1 sound/aoa
     45 sound/core
     17 sound/drivers
      5 sound/i2c
     35 sound/isa
      1 sound/last.c
      2 sound/oss
      1 sound/parisc
    117 sound/pci
      7 sound/pcmcia
      4 sound/ppc
      1 sound/sh
     20 sound/soc
      1 sound/sound_core.c
      7 sound/synth
     12 sound/usb
      1 tools/iio
      6 tools/include
      2 tools/lib
      6 tools/perf
      3 tools/power
      3 tools/testing
      4 tools/virtio
      1 usr/gen_init_cpio.c
      1 virt/kvm

Re: [PATCH] editorconfig: Add automatic editor configuration file

[Miguel Ojeda]

On Fri, Jul 3, 2020 at 9:31 AM Danny Lin <danny@kdrag0n.dev> wrote:
>
> Most of the other exceptions can be accomodated for with more specific
> rules below the base [*] section. I just went through most of the
> kernel's files and added rules for the vast majority of the exceptinos
> to the 8-column tab indent style, though there are still some that
> haven't been covered.

Very good! That looks much better.

Are there too many file types that use tabs? If not, then I think it
is best to add a section for "General tab" files like for the others,
in order to be explicit and to have the list around.

> It looks like some types of files lack consistent indentation, e.g.
> arch/mips/*/Platform and some shell scripts in scripts/ tools/testing/
> selftests/ftrace/test.d/kprobe/*.tc. There are also some files that were
> highly inconsistent even within themselves (e.g. drivers/gpu/drm/amd/
> amdkfd/cwsr_trap_handler_gfx*.asm), so setting indentation settings to
> something sane by default doesn't make them any worse. After all, no
> automated code style tooling is perfect and there will be edge cases
> where it breaks down.

Yeah, do not worry about inconsistencies. For `.clang-format`, I
picked the options based on 1) whether there was an official code
style guideline and 2) if not, the one that minimizes the number of
changes, i.e. the most popular one across files.

Cheers,
Miguel