Skip to content

✍️ 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.

License

Notifications You must be signed in to change notification settings

mikelorant/committed

Repository files navigation

Committed

Release Build License Codecov CodeFactor

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 First Steps Installation Usage Configuration Best Practises Shortcuts

demo

πŸ’‘ 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
  2. Before creating and applying a commit you will need to stage the files you wish to add with the git add command.

  3. 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
macOS Terminal options
iTerm2 Preferences Profile Keys
iTerm2 options

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: character
  emojiType: character

  # 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:

πŸ† 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:

⌨ 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

Visual Style

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

✏️ Authors ⭑

🎫 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.

Footnotes

  1. Print Git command on failure. ↩

About

✍️ 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.

Topics

Resources

License

Stars

Watchers

Forks

Languages