Skip to content
jsworkbench.
Learning path
Advanced18 min

Branch conventions and commit messages

Understand the idea

Short branch names and commit messages that say why save the next reader a search.

The idea

The graph already shows what changed. Names tell a teammate where to look and why the exists. Use a short name for the intent, such as fix-empty-login. Write a message that would still make sense next to the diff in a .

What changes

The commands are the ones you already know: git switch -c fix-empty-login and git commit -m "Reject empty login instead of submitting it". What changes is the reader's job. git log --oneline becomes a list of reasons. The branch list becomes a list of tasks. Conventions do not move HEAD. They make the labels worth reading.

Names a teammate can use
WeakClearWhy
wipfix-empty-loginThe branch says the task
updateReject empty login instead of submitting itThe message says why
asdfdocs: describe the three statesA prefix can name the kind of change

The command

Create a branch whose name is the task. Commit with a message a reviewer could repeat without opening the file. Then git log --oneline --graph. If the line only makes sense to you today, rewrite it with git commit --amend before anyone else has fetched it.

The mistake

Check your graph

The branch chip should read like a task, and the commit message should say why. A teammate who only reads the graph should know which node to open.

Your repository

Name a branch and a commit so a teammate can tell the intent without opening the diff.

  1. Step 1

    Name the branch for the task

    fix-empty-login says what the work is. If you already created it, run git switch fix-empty-login.

  2. Step 2

    Make the change

    In the editor, set login.txt to: Reject an empty login instead of submitting it

  3. Step 3

    Stage it

    The diff is the what. The next message is the why.

  4. Step 4

    Write the reason

    A teammate should understand this line without opening the file.

  5. Step 5

    Read the graph as a teammate

    The branch name is the task. The commit message is the reason.

The editor edits the working tree. Start a repository and the files appear here.

Follow the steps. Each command step can be placed in the terminal. Edit files in the editor, then stage them.
Supported command reference
  • init
  • add <path> | add .
  • commit -m "message" | commit --amend -m "message"
  • status
  • diff | diff --staged
  • log | log --oneline | log --graph | log --oneline --graph
  • show [ref]
  • branch | branch <name> | branch -d <name>
  • checkout <ref> | checkout -b <name> | switch <name> | switch -c <name>
  • merge <branch>
  • rebase <branch> | rebase -i <branch> | rebase --edit-todo <pick|drop|reword> <hash> [message] | rebase --continue | rebase --abort
  • cherry-pick <ref>
  • reset --soft <ref> | reset --mixed <ref> | reset --hard <ref>
  • revert <ref>
  • stash | stash list | stash pop | stash apply
  • restore <path> | restore --staged <path>
  • remote | remote add <name> <repo-slug>
  • clone <repo-slug> | git clone <repo-slug> | git fork <repo-slug>
  • fetch [remote] | pull [remote] [branch] | push [remote] [branch] | push --force [remote] [branch]
  • blame <path>
  • reflog
  • tag | tag <name> [ref] | tag -d <name>
  • bisect start | bisect good [ref] | bisect bad [ref] | bisect reset
  • config <key> <value> | config --list
  • write <path> <text> (workbench: edit the working tree)
  • issue new "title" | pr new <source> <target> "title" | review "comment" | review --request-changes "comment"

Commit graph

No commits yet. git init creates the first one.

Quiz

A quick check for understanding. Retry as often as you like; your learning path stays open.

01What should a commit message say?
02What makes a useful branch name?

Ready to call this one understood?

Mark this lesson complete to earn 200 XP. You can always revisit it.

Sign in to save progress
Next lesson