Merge pull request #2 from DecimalTurn/draft

Add extensions and remove * text=auto
DecimalTurn · Jun 18, 2024 · 7ab489d · 7ab489d
2 parents 0f73e89 + 2e49d80
commit 7ab489d
Show file tree

Hide file tree

Showing 6 changed files with 155 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ This project is here to help you configure your VBA project on GitHub and discus
 - [Why should you include `.gitignore` and `.gitattributes` files to your project?](#why-should-you-include-gitignore-and-gitattributes-files-to-your-project)
 - [.gitignore](#gitignore)
 - [.gitattributes](#gitattributes)
-- [Should you include a `.editorconfig` file in your repo?](#should-you-include-a-editorconfig-file-in-your-repo)
+- [Should you include a `.editorconfig` file in your repository?](#should-you-include-a-editorconfig-file-in-your-repository)
 - [.editorconfig](#editorconfig)
 
 # Why should you include .gitignore and .gitattributes files to your project?
@@ -53,15 +53,23 @@ This template will make sure that Git doesn't perform any line endings or text e
 
 If you need a refresher or you've never had to think about how line endings work, I'd suggest having a look at the introduction of [this article](https://www.hanselman.com/blog/carriage-returns-and-line-feeds-will-ultimately-bite-you-some-git-tips) by Scott Hanselman. It will explain the origin of this CRLF vs LF issue.
 
-Now, you'll first notice the use of `* text=auto eol=lf` in the template. The first part (`* text=auto`) is to let Git decide automatically for all files (`*`) if the `text` attribute should be "set" (aka. true) or "unset" (aka. false). Having the `text` attribute set "enables end-of-line conversion: When a matching file is added to the index, the file's line endings are normalized to LF in the index." <sup>1</sup>. Usually, Git is pretty good at determining if a file is a text or binary file, but it's important to place the `* text=auto` line at the top, so that the lines that come after can override this behavior when we need it to<sup>2</sup>.
+When creating a `.gitattributes`, a common practice is to include `* text=auto` at the top of your file. This can be useful for certain cross-platform projects, but it's not really useful for VBA projects and it can even be a problem if that's the only entry you have in your `.gitattributes` file.
 
-The second part (`eol=lf`) tells Git to perform line conversion to LF during on checkout. Since LF is usually recognized as the default now, this is a good practice. The remaining lines in the .gitattributes file are then there to deal with the exceptions to this rule.
+`* text=auto` is normally to let Git decide automatically for all files (`*`) if the `text` attribute should be "set" (aka. true) or "unset" (aka. false). Having the `text` attribute set "enables end-of-line conversion: When a matching file is added to the index, the file's line endings are normalized to LF in the index." <sup>1</sup>. Usually, Git is pretty good at determining if a file is a text or binary file, but it's important to place that line at the top, so that the lines that come after can override this behavior when we need it to<sup>2</sup>.
+
+In the suggested template, we don't include `* text=auto` because having this as the default for all file types requires you to be careful to override every case where you don't want that behavior. All that without seeing much benefit. Feel free to add it if you prefer, but make sure to include the other entries in the `.gitattributes` template file as they will deal with the exceptions to this rule.
 
 ### Why prevent LF normalization for VBA code?
 
-The VBE's heyday was in the 90s. Back then, Windows was running on CRLF and there was no intentions of supporting that competing LF standard. Windows has now moved on and even Notepad supports LF nowadays, but the VBE does not sadly. 
+The VBE's heyday was in the 90s. Back then, Windows was running on CRLF and there were no intentions of supporting that competing LF standard. Windows has now moved on and even Notepad supports LF nowadays, but the VBE does not sadly.
+
+This means that the VBE expects files to use CRLF and if you try to import a VBA code file with LF, you'll experience weird bugs such as the one described [here](https://github.com/VBA-tools/VBA-Dictionary/issues/5), [here](https://github.com/VBA-tools/VBA-Dictionary/issues/12), [here](https://github.com/VBA-tools/VBA-Dictionary/issues/38), [here](https://github.com/VBA-tools/VBA-JSON/issues/265) or [here](https://www.reddit.com/r/vba/comments/1ddpvtb/comment/l875ps5/). For that reason, the recommended template `.gitattributes` file in this repository prevents Git from performing LF normalization on VBA code files (that you've likely exported from the VBE).
+
+All the issues mentioned in the previous paragraph have a common cause: People tried to download a single VBA code file, but GitHub gave them the "raw" file. The file they got was taken from inside the repository without any normalization back to CRLF. This normalization is taken care of when you clone or downloading the repository as a `.zip` file. In the end, if we don't want new comers to face any of theses issues, the simplest option is to prevent all line normalization like what is suggested here.
+
+### What about VBA projects with macOS support?
 
-This means that the VBE expects files to use CRLF and if you try to import a VBA code file with LF, you'll experience weird bugs such as the one described [here](https://github.com/VBA-tools/VBA-Dictionary/issues/5), [here](https://github.com/VBA-tools/VBA-Dictionary/issues/12), [here](https://github.com/VBA-tools/VBA-Dictionary/issues/38), [here](https://github.com/VBA-tools/VBA-JSON/issues/265) or [here](https://www.reddit.com/r/vba/comments/1ddpvtb/comment/l875ps5/). For that reason, the recommended template .gitattributes file in this repo prevents Git from performing LF normalization on files using CRLF (that you've likely exported from the VBE).
+Even if your VBA project has support for macOs, the Mac version of the VBE still expects the code files that it imports to use CRLF.
 
 ### Does the use of `-text` affect how Git performs diffs?
 
@@ -97,12 +105,12 @@ Get-WinSystemLocale | Select-Object @{ n='ANSI Code Page';   e={ $_.TextInfo.Ans
 
 ## Should you specify the `linguist-language` attribute?
 
-Regarding the attribute `linguist-language=vba`, I choose not to include it in the suggested template because I believe that GitHub's system to detect if a file is VBA or not is decent and if your files aren't detected as VBA, it might be telling you something about your code.
+Regarding the attribute `linguist-language=vba`, I choose not to include it in the suggested template because I believe that GitHub's system to detect if a file is VBA or not is decent enough and if your files aren't detected as VBA, it might be telling you something about your code.
   - Make sure that your files include the VBE's metadata such as the `Attribute VB_Name = "..."`
   - Use the right file extensions
   - If you `.bas` files doesn't contain any VBA specific syntax, maybe it's OK if is classified as VB6 instead.
 
-# Should you include a .editorconfig file in your repo?
+# Should you include a .editorconfig file in your repository?
 
 The `.editorconfig` file is used by many popular IDE and text editor to specify the default behavior when dealing with certain text files. If you want to make it easier for people to use other editors than the VBE, you can always include that file in your project.
 

diff --git a/gitattributes/CRLF everywhere/.gitattributes b/gitattributes/CRLF everywhere/.gitattributes
@@ -1,17 +1,50 @@
-# By default, auto detect text files and perform LF normalization
-* text=auto                 eol=lf
+# Don't perform any line ending conversions by default
 
-# VBA extensions - Prevent LF normalization
+# VBA extensions - Prevent LF normalization (bas, cls, frm, vba)
 *.[bB][aA][sS]              -text diff
 *.[cC][lL][sS]              -text diff
 *.[fF][rR][mM]              -text diff
 *.[vV][bB][aA]              -text diff
 
-# VBA extensions - Mark as binary
+# VBA extensions - Mark as binary (frm)
 *.[fF][rR][xX]              binary
-
-# AutoHotKey - Prevent LF normalization
-*.[aA][hH][kK]              -text diff
+
+############################################################################
+# Other languages in the VB family 
+############################################################################
+
+# VBS extensions - Prevent LF normalization (vbs)
+*.[vV][bB][sS]              -text diff
+
+# VB6 extensions - Prevent LF normalization (ctl, dsr, dob, pag, vbg, vbl, vbp, vbr, vbw)
+*.[cC][tT][lL]              -text diff
+*.[dD][sS][rR]              -text diff
+*.[dD][oO][bB]              -text diff
+*.[pP][aA][gG]              -text diff
+*.[vV][bB][gB]              -text diff
+*.[vV][bB][lL]              -text diff
+*.[vV][bB][pP]              -text diff
+*.[vV][bB][rR]              -text diff
+*.[vV][bB][wW]              -text diff
+
+# VB6 extensions - Mark as binary (ctx, dox, pgx)
+*.[cC][tT][xX]              binary
+*.[dD][oO][xX]              binary
+*.[pP][gG][xX]              binary
+
+# twinBASIC extensions  - Prevent LF normalization (twin, tbform)
+*.[tT][wW][iI][nN]          -text diff
+*.[tT][bB][fF][oO][rR][mM]  -text diff
+
+# twinBASIC extensions  - Mark as binary
+*.[tT][wW][iI][nN][pP][rR][oO][jJ]  binary
+
+############################################################################
+# Other Windows-specific extensions
+############################################################################
+
+# INI file extensions  - Prevent LF normalization
+*.[iI][nN][iI]              -text diff
 
 # Batch scripts - Prevent LF normalization
 *.[cC][mM][dD]              -text diff
@@ -29,7 +62,8 @@
 *.[xX][lL][sS][mM]          binary
 *.[xX][lL][sS][xX]          binary
 
-# Word documents (doc and docx)
+# Word documents (rtf, doc and docx)
+*.[rR][tT][fF]              diff=astextplain
 *.[dD][oO][cC]              diff=astextplain
 *.[dD][oO][cC][xX]          diff=astextplain
 
@@ -59,4 +93,3 @@
 
 # Other
 *.[pP][dD][fF]              diff=astextplain
-
diff --git a/gitattributes/CRLF in Working Directory only/.gitattributes b/gitattributes/CRLF in Working Directory only/.gitattributes
@@ -1,19 +1,53 @@
-# By default, auto detect text files and perform LF normalization
-* text=auto                 eol=lf
+# By default, auto-detect text files and perform CRLF to LF conversion at checkin. LF to Native line endings conversion at checkout.
+* text=auto
 
 # VBA extensions (bas, cls, frm and vba) - Enforce CRLF in working directory
-*.[bB][aA][sS]              text eol=crlf working-tree-encoding=CP1252
-*.[cC][lL][sS]              text eol=crlf working-tree-encoding=CP1252
-*.[fF][rR][mM]              text eol=crlf working-tree-encoding=CP1252
-*.[vV][bB][aA]              text eol=crlf working-tree-encoding=CP1252
+*.[bB][aA][sS]              text eol=crlf
+*.[cC][lL][sS]              text eol=crlf
+*.[fF][rR][mM]              text eol=crlf
+*.[vV][bB][aA]              text eol=crlf
 
 # Other VBA extensions (frx) - Mark as binary
 *.[fF][rR][xX]              binary
-
-# AutoHotKey (ahk) - Enforce CRLF in working directory
-*.[aA][hH][kK]              text eol=crlf
 
-# Batch scripts (cmd and bat) - Enforce CRLF in working directory
+############################################################################
+# Other languages in the VB family 
+############################################################################
+
+# VBS extensions - Prevent LF normalization (vbs)
+*.[vV][bB][sS]              text eol=crlf
+
+# VB6 extensions - Prevent LF normalization (ctl, dsr, dob, pag, vbg, vbl, vbp, vbr, vbw)
+*.[cC][tT][lL]              text eol=crlf
+*.[dD][sS][rR]              text eol=crlf
+*.[dD][oO][bB]              text eol=crlf
+*.[pP][aA][gG]              text eol=crlf
+*.[vV][bB][gB]              text eol=crlf
+*.[vV][bB][lL]              text eol=crlf
+*.[vV][bB][pP]              text eol=crlf
+*.[vV][bB][rR]              text eol=crlf
+*.[vV][bB][wW]              text eol=crlf
+
+# VB6 extensions - Mark as binary (ctx, dox, pgx)
+*.[cC][tT][xX]              binary
+*.[dD][oO][xX]              binary
+*.[pP][gG][xX]              binary
+
+# twinBASIC extensions  - Prevent LF normalization (twin, tbform)
+*.[tT][wW][iI][nN]          text eol=crlf
+*.[tT][bB][fF][oO][rR][mM]  text eol=crlf
+
+# twinBASIC extensions  - Mark as binary
+*.[tT][wW][iI][nN][pP][rR][oO][jJ]  binary
+
+############################################################################
+# Other Windows-specific extensions
+############################################################################
+
+# INI file extensions  - Prevent LF normalization
+*.[iI][nN][iI]              text eol=crlf
+
+# Batch scripts - Prevent LF normalization
 *.[cC][mM][dD]              text eol=crlf
 *.[bB][aA][tT]              text eol=crlf
 
@@ -29,7 +63,8 @@
 *.[xX][lL][sS][mM]          binary
 *.[xX][lL][sS][xX]          binary
 
-# Word documents (doc and docx)
+# Word documents (rtf, doc and docx)
+*.[rR][tT][fF]              diff=astextplain
 *.[dD][oO][cC]              diff=astextplain
 *.[dD][oO][cC][xX]          diff=astextplain
 

diff --git a/gitattributes/CRLF in Working Directory only/README.md b/gitattributes/CRLF in Working Directory only/README.md
@@ -1,4 +1,4 @@
-This version will make sure that VBA related files are encoded using UTF-8 and Unix-style line endings (LF) when they are committed to the Git index. This is to better work with the GitHub UI which is often expecting those specific encodings to work properly.
+This version will make sure that VBA related files contain Unix-style line endings (LF) when they are committed to the Git index. This is to better work with the GitHub UI which is often expecting those specific encodings to work properly.
 
-Disclaimer: Converting your files to use UTF-8 and/or LF line endings means that people that want to download your code might have a problem if they try to download the a raw file with code.
+Disclaimer: Converting your files to LF line endings means that people that want to download your code might have a problem if they try to download the a raw file with code.
 ![Alt text](../../docs/img/ScreenCapDownloadRawFile.png)
diff --git a/gitattributes/Force CRLF everywhere with filters/.gitattributes b/gitattributes/Force CRLF everywhere with filters/.gitattributes
@@ -1,6 +1,6 @@
 # This .gitattributes file is configured to fight against Git to keep CRLF inside the index. 
 
-# Important: This fie makes use of the a filter named "crlf". This filter users the unix2dos command that is included with Git for Windows (and most Unix distributions).
+# Important: This file makes use of the a filter named "crlf". This filter uses the unix2dos command that is included with Git for Windows (and most Unix distributions).
 # To make sure this filter is active, you have 2 options (A or B): 
 # A) 
 # - Run the following command at the root of your Git repository: git config --add filter.crlf.clean unix2dos
@@ -9,24 +9,54 @@
 #   (The reason why we need the ".." is to move one folder up because the config file is located in the .git subfolder.)
 # - Then make sure that you have a file named .gitconfig in your Git repository like this file: https://github.com/DecimalTurn/VBA-on-GitHub/blob/main/gitattributes/Force%20CRLF%20everywhere%20with%20filters/.gitconfig
 
-# By default, auto detect text files and perform LF normalization
-* text=auto                 eol=lf
-
 # VBA extensions - Enforce CRLF using a filter
-*.[bB][aA][sS]              filter=crlf -text
-*.[cC][lL][sS]              filter=crlf -text
-*.[fF][rR][mM]              filter=crlf -text
-*.[vV][bB][aA]              filter=crlf -text
+*.[bB][aA][sS]              filter=crlf -text diff
+*.[cC][lL][sS]              filter=crlf -text diff
+*.[fF][rR][mM]              filter=crlf -text diff
+*.[vV][bB][aA]              filter=crlf -text diff
 
 # VBA extensions - Mark as binary
 *.[fF][rR][xX]              binary
-
-# AutoHotKey - Enforce CRLF using a filter
-*.[aA][hH][kK]              filter=crlf -text
+############################################################################
+# Other languages in the VB family 
+############################################################################
+
+# VBS extensions - Prevent LF normalization (vbs)
+*.[vV][bB][sS]              filter=crlf -text diff
+
+# VB6 extensions - Prevent LF normalization (ctl, dsr, dob, pag, vbg, vbl, vbp, vbr, vbw)
+*.[cC][tT][lL]              filter=crlf -text diff
+*.[dD][sS][rR]              filter=crlf -text diff
+*.[dD][oO][bB]              filter=crlf -text diff
+*.[pP][aA][gG]              filter=crlf -text diff
+*.[vV][bB][gB]              filter=crlf -text diff
+*.[vV][bB][lL]              filter=crlf -text diff
+*.[vV][bB][pP]              filter=crlf -text diff
+*.[vV][bB][rR]              filter=crlf -text diff
+*.[vV][bB][wW]              filter=crlf -text diff
+
+# VB6 extensions - Mark as binary (ctx, dox, pgx)
+*.[cC][tT][xX]              binary
+*.[dD][oO][xX]              binary
+*.[pP][gG][xX]              binary
+
+# twinBASIC extensions  - Prevent LF normalization (twin, tbform)
+*.[tT][wW][iI][nN]          filter=crlf -text diff
+*.[tT][bB][fF][oO][rR][mM]  filter=crlf -text diff
 
-# Batch scripts - Enforce CRLF using a filter
-*.[cC][mM][dD]              filter=crlf -text
-*.[bB][aA][tT]              filter=crlf -text
+# twinBASIC extensions  - Mark as binary
+*.[tT][wW][iI][nN][pP][rR][oO][jJ]  binary
+
+############################################################################
+# Other Windows-specific extensions
+############################################################################
+
+# INI file extensions  - Prevent LF normalization
+*.[iI][nN][iI]              filter=crlf -text diff
+
+# Batch scripts - Prevent LF normalization
+*.[cC][mM][dD]              filter=crlf -text diff
+*.[bB][aA][tT]              filter=crlf -text diff
 
 ############################################################################
 # Optional Sections
@@ -40,7 +70,8 @@
 *.[xX][lL][sS][mM]          binary
 *.[xX][lL][sS][xX]          binary
 
-# Word documents (doc and docx)
+# Word documents (rtf, doc and docx)
+*.[rR][tT][fF]              diff=astextplain
 *.[dD][oO][cC]              diff=astextplain
 *.[dD][oO][cC][xX]          diff=astextplain
 
@@ -70,4 +101,3 @@
 
 # Other
 *.[pP][dD][fF]              diff=astextplain
-
diff --git a/gitattributes/Force CRLF everywhere with filters/README.md b/gitattributes/Force CRLF everywhere with filters/README.md
@@ -1,6 +1,7 @@
-So you've found the CRLF strict section. Good. Very Good. That means you are a rebel. A non-comforist.
+So you've found the CRLF strict section. Good. Very Good. That means you are a rebel. A non-conformist.
 
 The .gitattributes in this sub-folder is there to help you go against the desires of Git to convert you line endings to LF and your Windows "ANSI" encoding to UTF-8.
 
-- Make sure to also add the .gitconfig file at the root of your repository
-- Note that we can't include the file encoding otherwise Git will perform the conversion. We can't let Git know anything. The more it knows, the easier it is for Git to try and "help us" by converting our code.
+For this to work, make sure to also add the .gitconfig file at the root of your repository. Note that we can't include the file encoding otherwise Git will perform the conversion. We can't let Git know anything. The more it knows, the easier it is for Git to try and "help us" by converting our code.
+
+> Caveat: For very large repos, having filters configured can noticeably increase the time it takes to commit changes and perform certain Git operations.