|
| 1 | +# Vision and Design Principles |
| 2 | + |
| 3 | +## Vision |
| 4 | + |
| 5 | +Lazygit's vision is to be the most enjoyable UI for git. |
| 6 | + |
| 7 | +## Design Principles |
| 8 | + |
| 9 | +There are seven (sometimes contradictory) design principles we follow: |
| 10 | + |
| 11 | +- Dicoverability |
| 12 | +- Simplicity |
| 13 | +- Safety |
| 14 | +- Power |
| 15 | +- Speed |
| 16 | +- Conformity with git |
| 17 | +- Think of the codebase |
| 18 | + |
| 19 | +### Discoverability |
| 20 | + |
| 21 | +TUI's are notoriously hard to learn, thanks to limited screen real-estate to provide contextual help and a general lack of effort on the part of developers to make things obvious. We want Lazygit to buck the trend and be easy for a new user to grok. |
| 22 | + |
| 23 | +Examples: |
| 24 | + |
| 25 | +- Clearly document all the features/configuration options |
| 26 | + - e.g. gifs in the README |
| 27 | +- Document how to solve various git problems with Lazygit |
| 28 | + - This is something we don't have yet but should: a section in the docs explaining how Lazygit can help you in various scenarios |
| 29 | +- Use tooltips to explain what actions will do |
| 30 | +- Make it easy for users to ask questions and get answers from the community |
| 31 | +- Make it easy to find entities and actions from within Lazygit |
| 32 | +- Use visual elements to make things obvious |
| 33 | + - e.g. '<-- YOU ARE HERE' label when rebasing |
| 34 | +- Don't require the user to memorise keybindings |
| 35 | + - e.g. when the user is mid-rebase, we prominently show that the keybinding for viewing rebase options is 'm' |
| 36 | +- When the user performs an action in Lazygit, make the impact obvious |
| 37 | + - If the affected entity isn't visible, show a toast notification |
| 38 | +- If a keybinding is disabled, give a reason why |
| 39 | + |
| 40 | +### Simplicity |
| 41 | + |
| 42 | +The git CLI is very complex but most git use cases are simple. Lazygit needs to ensure that simple use cases are easy to satisfy. |
| 43 | + |
| 44 | +- Make the most common use cases dead-simple (staging files, committing, pulling/pushing) |
| 45 | +- Don't overwhelm the user with options |
| 46 | +- Use sensible defaults |
| 47 | +- We already have too many configuration options: think hard before adding any new ones |
| 48 | + |
| 49 | +### Safety |
| 50 | + |
| 51 | +It's easy to screw things up in git so Lazygit should try to protect the user from screwing things up. |
| 52 | + |
| 53 | +- Prompt for a confirmation before doing anything that's hard to reverse |
| 54 | +- Make it easy to correct mistakes |
| 55 | + - e.g. undo action |
| 56 | + - the escape key should get you out of most transient situations (rebasing, diffing, etc) |
| 57 | + |
| 58 | +## Power |
| 59 | + |
| 60 | +Users shouldn't have to drop down the CLI _too_ often. Lazygit should be able to handle some complex use cases. |
| 61 | + |
| 62 | +- Make complex (but common) CLI flows simple |
| 63 | + - e.g. interactive rebasing |
| 64 | +- Use the custom commands system to handle the really rare complex edge-cases |
| 65 | + |
| 66 | +### Speed |
| 67 | + |
| 68 | +Pro users should be able to move at lightning speed with Lazygit. |
| 69 | + |
| 70 | +- Always think about the number of keypresses involved in a given UX flow |
| 71 | +- Make lazygit performant and responsive |
| 72 | +- Think about the individual commands being run and how fast they are |
| 73 | +- Startup should be FAST. If you want to run something at startup that is slow, make it non-blocking. |
| 74 | +- Support muscle-memory |
| 75 | + - Prefer disabling menu items instead of hiding them so that muscle memory can be used to select the desired menu item |
| 76 | + - Try to make keybinding intuitions to transfer across contexts (e.g. 'd' for destroy) |
| 77 | + - When changing keybindings in a new release, always consider what will happen if a user does not read the release notes and relies on muscle memory. |
| 78 | + |
| 79 | +### Conformity with git |
| 80 | + |
| 81 | +Satisfying the use-cases of git users is more important than perfectly conforming to git's API, but even obscure parts of git's API were motivated by real use-cases. |
| 82 | + |
| 83 | +- Users should only have to drop down to the git CLI in rare circumstances |
| 84 | +- Honour the git config |
| 85 | + - Don't override anything set in the git config without the user's permission |
| 86 | +- Work with git, not against it. |
| 87 | + - Too much magic will get us into trouble |
| 88 | +- Avoid storing Lazygit-specific session state that could instead be stored in git |
| 89 | +- Ensure that Lazygit can represent the state of any repo |
| 90 | +- Sometimes git's default behaviour is just silly and we'll make the call to override but it should be a well-considered decision. |
| 91 | + |
| 92 | +### Think of the codebase |
| 93 | + |
| 94 | +Will somebody PLEASE think of the codebase! |
| 95 | + |
| 96 | +Some features are not worth the added complexity in the codebase. The more this codebase grows, the harder it will be to make the changes that everybody wants. |
| 97 | + |
| 98 | +## Resolving conflicts |
| 99 | + |
| 100 | +Many of the above objectives are directly antithetical to one another. If you add an extra confirmation prompt for the sake of _safety_, you're sacrificing _speed_. If you support toggling various git flags in the name of _power_, you're sacrificing _simplicity_. There are a few things to say here. |
| 101 | + |
| 102 | +When there are conflicts, we need to make a judgement call. In general we should err on the side of safety and simplicity as the default, with the ability for users to make things faster / more powerful either through configuration or separate keybindings. |
| 103 | + |
| 104 | +This does not mean for example that force pushes should be impossible without being manually enabled: force pushes are table stakes for anybody who rebases. But it does mean that a confirmation popup should appear when force pushing. |
0 commit comments