committed

README

Committed

Committed is a WYSIWYG Git commit editor that helps improve the quality of your commits by showing you the layout in the same format as git log.

💡 Highlights ⭡

• Built-in multiline editor with rich capabilities.
• Custom emoji selector providing popular sets to choose from.
• Switch author before applying the commit.
• Inline text interface mimics the Git log output.
• Dynamic subject line counter.
• Toggle appending sign-off required by many open source projects.
• Automatically hard wraps body to 72 characters.
• Best practise recommendations.
• Import and amend previous commit.
• Adaptive colours with light and dark themes.

🐾 First Steps ⭡

1. Install using Homebrew.

brew install mikelorant/committed/committed

1. Before creating and applying a commit you will need to stage the files you wish to add with the git add command.

2. Committed replaces the git commit command and all you need to do to commit your change is to run:

committed

It is also possible to amend your previous commit with:

committed --amend

Once the UI has appeared take note of the keyboard shortcuts shown at the bottom of the interface.

 Alt + <enter> Commit <s> Sign-off </> Help                Summary <tab>
Ctrl +     <c> Cancel                                       Author <tab> + Shift

These shortcuts will help you apply or cancel a commit and navigate between the different components. Pressing enter on most components will automatically switch you to the next one.

💬 Purpose ⭡

The benefits of high quality commits are well documented however the tooling to follow these practises has been lacking. In most cases you are either providing a single line commit message or forced into a full screen editor which has no knowledge of recommended Git practises.

It is common to accidentally commit to the wrong branch or use the incorrect author name. Improving clarity of commits with emojis or detailed messages is often frustrating.

For many, knowing what makes a good commit is not even thought about.

Committed attempts to solve these problems by first educating on best practises. It then helps guide and enforce these de factor standards while showing how the commit will end up being displayed to other users.

The interface does not take over the sceen or force switching to another application. All actions are done with the keyboard which is consistent with the Git command which is often used before the actual commit. Having an editor which allows for more advanced cursor movement and editing assists with revising rather than accepting what has already been written.

These capabilities all contribute to helping create a commit message that is useful.

⚠️ Limitations ⭡

Option Key

The option key needs to be set to send the meta or esc+ keycode. Terminals such as macOS Terminal or iTerm2 may not have this as default. If not set correctly it will not be possible to apply a commit.

To make these changes following the instructions below.

Terminal	Setting
macOS Terminal	Profiles Keyboard
iTerm2	Preferences Profile Keys

The alternative keyboard shortcut ⌥ Option + \ can also be used to apply a commit.

Rendering Borders

Terminals render emojis differently and this makes alignment of borders complicated and difficult. It is an ongoing process to improve the compatibility with terminals. The following list are the terminals that have been tested. Other terminals may display correctly and feedback would be appreciated to help update the list.

Terminal	Status	Notes
macOS Terminal
iTerm2
VS Code
Hyper
Alacritty
WezTerm
ttyd		Requires compatibility option set.
kitty		Requires compatibility option set.

💾 Installation ⭡

Install Committed with Homebrew.

brew install mikelorant/taps/committed

⚙ Usage ⭡

Committed is a WYSIWYG Git commit editor

Usage:
  committed [flags]
  committed [command]

Available Commands:
  completion   Generate the autocompletion script for the specified shell
  help         Help about any command
  hook         Install and uninstall Git hook
  list         List settings with profiles or IDs
  version      Print the version information

Flags:
      --config string     Config file location (default
                          "$HOME/.config/committed/config.yaml")
      --snapshot string   Snapshot file location (default
                          "$HOME/.local/state/committed/snapshot.yaml")
      --dry-run           Simulate applying a commit (default false)
  -a, --amend             Replace the tip of the current branch by creating a new commit
  -h, --help              help for committed
  -v, --version           version for committed

Use "committed [command] --help" for more information about a command.

List

Usage:
  committed list [command]

Available Commands:
  emojis       List emoji profiles
  themes       List theme IDs

Hook

Usage:
  committed hook [flags]

Flags:
      --install     Install Git hook
      --uninstall   Uninstall Git hook

🎛 Configuration ⭡

No configuration is necessary however there are some values that can be changed based on preference.

Committed defaults to using a config file located at $HOME/.config/committed/config.yaml.

view:
  # Starting component focus.
  # Values: author, emoji, summary
  # Default: emoji
  focus: emoji

  # Emoji selector placement in relation to subject.
  # Values: above, below
  # Default: below
  emojiSelector: below

  # Emoji set to use.
  # Values: gitmoji, devmoji, emojilog
  # Default: gitmoji
  emojiSet: gitmoji

  # Theme to display. Dark and light backgrounds have different themes.
  # Dark values:
  #   builtin_dark, dracula, gruvbox_dark, nord, retrowave,
  #   solarized_dark_higher_contrast, tokyo_night
  # Dark default: builtin_dark
  # Light values:
  #   builtin_light, gruvbox_light, builtin_solarized_light,
  #   builtin_tango_light, tokyo_night_light
  # Light default: builtin_light
  theme: builtin_dark

  # Colour profile for displaying themes.
  # Values: adaptive, dark, light
  # Default: adaptive
  colour: adaptive

  # Terminal compatibility.
  # Values: default, ttyd
  # Default: default
  compatibility: default

  # Highlight active component.
  # Value: true, false
  # Default: false
  highlightActive: false

  # Ignore Git global author.
  # Value: true, false
  # Default: false
  ignoreGlobalAuthor: false

commit:
  # Emoji format in commit.
  # Values: shortcode, character
  # Default: shortcode
  emojiType: shortcode

  # Enable author sign-off for commits.
  # Values: true, false
  # Default: false
  signoff: false

authors:
  # List of extra authors.
  - name: John Doe
    email: john.doe@example.com

Themes

There are a number of themes available that modify the colours. By default, the background colour is detected which changes the choices of themes. This detection can be disabled by setting the colour profile in the configuration. The first theme of each set is the default theme applied.

Dark Themes

Name	ID
Builtin Dark	builtin_dark
Dracula	dracula
Gruvbox Dark	gruvbox_dark
Nord	nord
Retrowave	retrowave
Solarized Dark Higher Contrast	solarized_dark_higher_contrast
Tokyo Night	tokyo_night

Light Theme

Name	ID
Builtin Light	builtin_light
Builtin Solarized Light	builtin_solarized_light
Builtin Tango Light	builtin_tango_light
Gruvbox Light	gruvbox_light
Tokyo Night Light	tokyo_night_light

Emoji Profiles

Popular emoji sets can be set as the default profile:

• Gitmoji
• Devmoji
• Emoji-Log

🏆 Best Practises ⭡

To create a well formed commit, these are some of the best practises that are often cited.

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.

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.

Further paragraphs come after blank lines.

• Bullet points are okay, too

• Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here

• Use a hanging indent

Source: Tim Pope

The placeholder text for the summary and body will show these recommendations.

Related links:

• Joel Parker Henderson
• Chris Beams

⌨ Shortcuts ⭡

The global shortcuts can be used within any view.

Key Binding	Command
⌥ Option + ⏎ Enter	Commit
⌥ Option + \	Commit
⌥ Option + S	Toggle sign-off
⌥ Option + T	Toggle theme
⌥ Option + /	Help
⌥ Option + 1	Focus author
⌥ Option + 2	Focus emoji
⌥ Option + 3	Focus summary
⌥ Option + 4	Focus body
⌃ Control + C	Cancel
⇥ Tab	Next component
⇧ Shift + ⇥ Tab	Previous component

The emoji shortcuts are limited to the emoji view only.

Key Binding	Command
⌫ Delete	Clear emoji
⎋ Escape	Reset filter
⇟ Page Down	Next page
⇞ Page Up	Previous page

📚 Tips ⭡

Aliases

Shell or Git aliases can be used to tailor Committed to your preferred workflow. An example Git alias is as follows:

git config --global alias.co '! committed'

You can then commit changes with:

git co

Prepare Message Hook

Committed can be installed as a Git prepare message hook. Be aware that any existing prepare-commit-msg hook will not be replaced and it is necessary to remove this hook before installing.

Installation:

committed hook --install

Removal:

committed hook --uninstall

Editor

Committed can replace the default Git editor which allows commits to be applied using git commit. Most of the standard Git command arguments can be used.

git config --global core.editor "committed --editor"

This can be removed with:

git config --global --unset-all core.editor

There are some limitations related to acting as an editor.

• Comment lines will be truncated to the width of the editor.
• Interactive rebasing and other operations which require edit commands may have visual issues. The first command may be part of the summary.
• Author cannot be set. The configured Git author will be used and will be selected using the default Git method (repository followed by global).
• When amending, subject line may be part of the body.
• When amending, emoji character or shortcode must be in the existing data set.
• When amending, summary will be truncated if more than 72 characters.
• When amending, trailers will be imported into the body.

Amend

There are certain limitations when amending commits and it is recommended only for use with commits created with Committed. The limitations share similarities with using Git as an editor.

• Emoji character or shortcode must be in the existing data set.
• Trailers will be imported into the body.
• Summary will be truncated if more than 72 characters.
• Lines will not reflow when editing the body.

⚖️ Comparison

Git Functions

Feature	Committed	Gitmoji CLI
Git hooks
Git editor replacement
Amend commit
Add files
Signed commits
Sign-off commits
Switch author
Save and load failed commits		[^1]

[^1]: Print Git command on failure.

Visual Style

Feature	Committed	Gitmoji CLI
Subject counter
Custom emojis
Mulitple emoji profiles
Multiline editor
Scope prompt
Themes
Hard wrap body width

✏️ Authors ⭡

• @mikelorant

🎫 License ⭡

MIT

👍 Thanks ⭡

Thanks to Carlos Cuesta for creating gitmoji and gitmoji-cli which was the inspiration for this project.

Thanks to Ahmad Awais for Emoji-Log and Folke Lemaitre for Devmoji.

Many thanks to David Ackroyd and Matt Hope for all their guidance with Go. Without their expertise I would never had the capability to build Committed.

Thanks to all the developers from Charm for their amazing set of libraries. Committed would never have looked the way it does without Bubble Tea, Lipgloss and Bubbles.

Thanks to Tim Pope for his Git commit recommendations which was a core component in the interface design.