So, I was trying to make a Git commit for a game I am working on so I could track my progress, and I wanted to include some formatted code.
Particularly, I wanted them to look like ðis kind of codeblock.
However, in the command line when I tried typing out my message
[calin@CalinArchPC RuntDeale]$ git commit -m "Merged `Level`, `LOVE`, and `XP` components into the `Player` component.
Changed the type of LOVE (Level Of ViolencE) from `i32` to `u32`.
Merged the `Layer` into the `Point` component.
Renamed the `Point` component to `Location` to accommodate the new field."
when I tried this I got a lot of unexpected errors.
I looked up the issue and immediately found out what was wrong, so instead I wanted to try it from a text editor, one Google search later and I ended up with git commit --amend.
So, this opened a file in VSCode, this made me happy, I thought this meant I was getting somewhere.
But nope, even after inserting the backticks via file it still didn't work.
So I looked up how I could possibly escape the character, which led me to this ServerFault post.
It says you can escape it with three (3) backslashes, so I tried doing a little test by inserting:
\\\`test\\\`
into my Git message.
The result... Nope. Didn't work.
So, how do I format code in Git?
For now I'll just write it without the backticks, it won't be too huge of a deal for now, but I'd like to know how I can format code for a future reader's reference.
Top comments (7)
Why do you want commit messages to look like code blocks?
It is a plain text field, you just add a brief explanation about what you did. The same way it will be read as plain text by any git GUI.
A more technical thingy that probably explain this behaviour is that youre using backticks in a linux command and the backticks allows you to assign the output of a shell command to a variable. So the terminal interpreter is probably trying to do something that you didn't mind, which is probably the reason why you're getting those error messages as well.
Code blocks in markdown format, like what we use here to show code are meant to be in the documentation of the project and git is not meant for that, it's "just" a VCS or version control system.
If you use GitLab for example, you'll see a
wikimenu item inside your project to add documentation. In Atlassian tools it's called confluence and so on. Or you can simply use the Readme.md file you should have in the root of your project :)Because I want to convey something is part of the code. If you read what I was doing you'd understand better. (Sorry if that sounds a little harsh or sassy.)
I was doing it so I could say:
Long story short, you can't. To use markdown (that's the notation based on which backticks are formatted as code) you need something that is able to read markdown and transform the output to something formatted, just like with any other markup language (html is another markup language as well and you cannot add html links or any other tag neither).
Moreover it will need to be interpreted by the repo website (gitlab, github, bitbucket...) And any git GUI (sourcetree, gitkraken...) Which won't happen.
Even if you end up wrapping it up as string (maybe using double quotes at the beginning and at the end of the text or so) you won't see the formatting you expect, because it will be interpreted as plain text.
Git history is not the place to give explanations neither, you don't say
"I changed getUsers function because...[explanation]",
Instead, you say:
"Updated getUsers feature to provide the new phoneNumber model property"
as example, and if you work with issues you should also set the ID:
"#14 Updated getUsers feature to provide the new validated model property"
So whoever reads the change history (or the changelog if it's extracted from the git history) can go to issues, search for the issue 14 and read the details about what had been done and why.
Moreover inside the issue could be a link to the wiki (doc) where you explain the implementation in more detail.
Hope it helps understanding every tool. 😁
That's what I do, but I'd like if that "getUsers" were "
getUsers\" purely for the point of distinction.Not "every", but for the given situation I guess it's an acceptable answer seeing as there isn't a workaround.
When you're dealing with plain text you just use that... Don't expect asterisks around a text to convert it into italic or bold, don't expect backticks to format it as code... The same way, don't expect
<a href="mywebsite">to render as link.Understanding that git commands are linux commands, so you are limited about some special chars that are reserved for different purposes is the first step.
The second one is to understand that, to get a formatted version of a marked content, you need some "engine" that transforms this marked input to a formatted output.
In this specific case you faced both in the same place 😅
I've read somewhere about using MD in git commit templates but the amount of marks you can use is very narrow, also the major part of git history GUIs don't mind interpreting the few ones that you can set without breaking into errors so... I wouldn't mind, sincerely.
It seems
git commit --amendisn't working period for some reason...But for some reason it worked when I added
-m <MESSAGE>in an inline command.What the hell???