This project is here to help you configure your VBA project on GitHub and discuss related issues.
- Why should you include
.gitignoreand.gitattributesfiles to your project? - .gitignore
- .gitattributes
- Should you include a
.editorconfigfile in your repository? - .editorconfig
.gitignore: This file is there to help Git determine what files it should ignore when committing changes to the project. It will allow you to avoid uploading content that you don't want to.
.gitattributes: This file will help you make sure that there won't be errors due to Git aplying conversions of your files.
A template .gitignore file is provided here:
📖 Template
Luckily for us, the VBE doesn't really create local or temporary files that you don't want to share outside of your computer (unlike for other IDEs like VScode). However, the Office application you are using might create temporary files that remain on the disk as long as the Office document is open to indicate to others that someone is working in the file (more details).
This is why an exclusion exists for this type of file (starting with ~$):
~$*
Sometimes, you'll be working from an actual Office document and only want to share the code as .bas, .frm and .frx files (not the office document itself). In that case, feel free to add extensions for Office documents extensions to your .gitignore file. Some of them are already in the template .gitignore file as commented-out lines. Just remove the "#" at the start of the line to add them back as needed.
You'll notice that the .gitignore (and .gitattributes) files make use of this syntax with brackets to specify file paths: eg.
*.[xX][lL][aA]This is because git configurations are case-sensitive: if we don't want to use 2 lines for each file extension (uppercase and lowercase version), we need to take advantage of the glob pattern syntax to combine lowercase and uppercase letters into pairs contained in those brackets. It's a bit harder to read, but I'm sure you'll get used to it.
A template .gitattributes file is provided here:
📖 Template
This template will make sure that Git doesn't perform any line endings or text encoding conversions.
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 by Scott Hanselman. It will explain the origin of this CRLF vs LF issue.
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.
* 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." 1. 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 to2.
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.
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, here, here, here, here or here. 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.
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.
The short answer is no, this won't affect how Git performs diffs.
The text attribute is only there to determine if Git will perform line endings conversion, the diff attribute is the one to determine how diffs are performed.
-text is not equivalent to the binary attribute. The binary attribute is a macro attribute equivalent to unsetting the 3 attributes:
-text -diff -merge
Setting the binary attribute will indeed prevent diffs from being performed since it includes -diff, not because of -text.
Probably no, unless you have code comments in a language other than English.
You should avoid non-ASCII characters in code that will run or will be shared outside your computer because those characters will appear differently on someone with a machine using a different encoding due to language configurations. This is especially important for text inside quotes because that will actually change the behavior of your code!
If you do have non-ASCII characters in your comments, a benefit of using working-tree-encoding is that people will have a better experience interacting with your code on GitHub. Indeed, GitHub has some issues when dealing with non-UTF8 encoding (example).
How to specify the working-tree-encoding?
To specify the encoding, you'd need to specify something like this:
*.bas -text diff working-tree-encoding=CP1252
In this case, I'm using CP1252 which is the usual Windows code page for Windows OS in North American and Western Europe, but it might differ on your system. To get the number that goes after "cp" on your local machine, you can run the following Powershell command :
Get-WinSystemLocale | Select-Object @{ n='ANSI Code Page'; e={ $_.TextInfo.AnsiCodePage } }
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.
To mitigate misindentification, make sure that:
- Your files include the VBE's metadata such as the
Attribute VB_Name = "..." - You use the right file extensions (bas, frm or vba)
If your .bas files are still marked as VB6, it's likely that they don't contain any VBA specific syntax, so maybe it's OK if is classified as VB6 instead 🤷. However, if you end up with the majority of you code identified as VB6, you can have a look a this troubleshooting guide.
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.
A template .editorconfig file is provided here:
📖 Template
Footnotes