VSCode - Git - GitHub basic explanations

The question has come up as to what to type into the git commit message area.

Before I get into the best practice, I want to explain a few things.

  1. The process to commit and sync with GitHub is a multiple step procedure. Here are the steps that occur in the background in VSCode. These steps show the command line process if you had to type them yourself.

    • You must enter a commit message in the box above the COMMIT button. This message box is explained in more details below.

      commit message box
    • Once you click the Commit button you are changing the status of the updated/new files to to a staged status   (git commit -m "message"). The command does 2 things at the same time. It adds the message and commits it to the list of files and sets the status to staged.
    • Most of you will have the branch name of MAIN. This is set as the default name in VSCode when you initialize the repository. I am using the name of main in the command line commands here.
    • Here are the steps that VSCode goes through when you click the sync button.
      1. Pull any changes from GitHub to local computer. (git pull origin/main)
      2. Push the staged files to GitHub. (git push origin origin/main)

    You can do all these commands at the same time in VSCode by doing a Commit & Sync. In VSCode this is done by click the blue button if it says Commit & Sync or click the down arrow on the right side of the button and select commit & sync

    VScode still runs the command line commands one at a time, so it runs all three commands listed above in that order, but you only click once to initiate the process.

    commit & sync

  2. This screenshot shows the commit & sync as one button. Most of you will only have COMMIT button.

    commit message box

    If you hit the commit button without a message, you will get an editor screen that looks something like this image. You have to type a message into line 1. You must save and close this editor screen for the commit process to continue.

    VScode editor commit

  3. What to type in the MESSAGE box.

    This is limited to 72 characters in length. The best commit messages follow the guidelines from this article: https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53

    Basically it is this type of message

    Write your commit message in the imperative: "Fix bug" and not "Fixed
            bug" or "Fixes bug." This convention matches up with commit messages
            generated by commands like git merge and git revert.

    From the page mentioned. There are 2 types of messages.

    Rules for a great git commit message style

    • Separate subject from body with a blank line
    • Do not end the subject line with a period
    • Capitalize the subject line and each paragraph
    • Use the imperative mood in the subject line
    • Wrap lines at 72 characters
    • Use the body to explain what and why you have done something. In most cases, you can leave out details about how a change has been made.

    Information in commit messages

    • Describe why a change is being made.
    • How does it address the issue?
    • What effects does the patch have?
    • Do not assume the reviewer understands what the original problem was.
    • Do not assume the code is self-evident/self-documenting.
    • Read the commit message to see if it hints at improved code structure.
    • The first commit line is the most important.
    • Describe any limitations of the current code.
    • Do not include patch set-specific comments.

    Details for each point and good commit message examples can be found on https://wiki.openstack.org/wiki/GitCommitMessages#Information_in_commit_messages

    If you want to add more data than the main message line, which is line 1 of the text, you hit the commit button before typing anything in the message box and hit commit. YOu will then see the editor screen where you add you message and then go below what is there and enter additional info. Remember to keep is as short as possible. Every one on the internet can read that info if they so wish.This screenshot gives you and example of that. The arrow pointing to the vertical line is the max width or characters allowed per line. The arrow at the bottom shows and additional message added.

    VSCode message details

There is a lot more info that can be given on this topic but I will leave that up to you to research and read if you so wish. This is just the info you need to get started.

VSCode documentation on Source Control and how it works within VSCode: https://code.visualstudio.com/docs/sourcecontrol/overview

To read commit messages and to look at what changes have been made. Open a repo, click on the commits. The number next to the word will be different for each repo

commits read

You will see a screen like this one. Click on the little box with the 3 dots and you will see the additional message if the person that did the commit added additional information.

details 2

In the image above you will notice an orange dot. That means the publication to the GitHub Pages is running. The check mark means that commit was successful.

In this next image it shows the additional message and it has a red circle with an X in it meaning the publication to GitHub Pages failed. In this case there was a second commit to GitHub before the GitHUb pages publication process was able to finish, so GitHub canceled the running process and started the new process.

message details 3

Let me know if you have any questions in Microsoft Teams.