affe - a full-fledged editor 🐵

                 __,__
        .--.  .-"     "-.  .--.
       / .. \/  .-. .-.  \/ .. \
      | |  '|  /   Y   \  |'  | |
      | \   \  \ 0 | 0 /  /   / |
       \ '- ,\.-"`` ``"-./, -' /
        `'-' /_   ^ ^   _\ '-'`
        .--'|  \._   _./  |'--.
      /`    \   \ `~` /   /    `\
     /       '._ '---' _.'       \     The more features an application
    /           '~---~'   |       \    provides, the harder will people
   /        _.             \       \   actually start using it.
  /   .'-./`/        .'~'-.|\       \
 /   /    `\:       /      `\'.      \        - An unknown monkey (2019)
/   |       ;      |         '.`;    /
\   \       ;      \           \/   /
 '.  \      ;       \       \   `  /
   '._'.     \       '.      |   ;/_
     /__>     '.       \_ _ _/   ,  '--.
   .'   '.   .-~~~~~-. /     |--'`~~-.  \
  // / .---'/  .-~~-._/ / / /---..__.'  /
 ((_(_/    /  /      (_(_(_(---.__    .'
           | |     _              `~~`
           | |     \'.
            \ '....' |
             '.,___.'

affe is a simple text editor enhanced with some fancy features. Its goal is to be a user-friendly terminal-based editor.

Screenshot:

Contents

• List of Features
• Quickstart
• Keyboard shortcuts
• FAQ
• Known Limitations
• Bonus

List of Features

• 📝 Text editor (wow!)
• 🎨 Syntax highlighting (fancy)
• ⚙️ Fuzzy Auto-Completion (this is aweso Ctrl+Space)
• 🔧 Inline git diff, git blame & git minimap (pretty useful)
• 🔤 Text selection (using mouse or Shift+Arrow Keys)
• ⌨️ Easy to remember keyboard shortcuts (Esc to exit, Ctrl+C to copy, Ctrl+A to select all, Ctrl+S to save)
• 🖱️ Mouse support (scrolling, clicking, text selection)
• 🔎 Find-and-replace functionality

Quickstart

Install the latest release from affe.sh or run affe from source:

Prerequisites:

• OS: Linux or macOS
• Python 3.10 or higher
• Packages:
  • git (for git integration features)
  • xclip (X11) or wl-clipboard (Wayland) (optional, for non-headless Linux systems to use the system clipboard)

git clone https://github.com/Leistungsabfall/affe.git
cd affe
python3.14 -m venv env # Replace python3.14 with your python version
. env/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Then, to start affe, run:

python src/main.py

To make affe available as a command, run:

./scripts/install.sh dist
cd dist
python3.14 -m venv env # Replace python3.14 with your python version
. env/bin/activate
python -m pip install --upgrade pip
pip install -r res/requirements.txt
deactivate

Finally, add the following line to your shell profile file (e.g. ~/.profile or ~/.zprofile):

export PATH="$PATH:<path-to-dist-folder>" # Replace <path-to-dist-folder> with the actual path to the dist folder

You can now start affe by simply running affe in the terminal.

Keyboard shortcuts

All keyboard shortcuts are designed with the intent to be intuitive. So you may already know most of them from Notepad++ or your favorite IDE.

Basic

Key Combination	Function
Esc	Exit
Ctrl+S	Save
Ctrl+Z	Undo
Ctrl+Y	Redo
Ctrl+C	Copy (if nothing is selected the whole line is copied)
Ctrl+V	Paste
Ctrl+X	Cut (if nothing is selected the whole line is cut)
Ctrl+A	Select all
Ctrl+F	Open Find toolbar
Ctrl+R	Open Replace toolbar

Advanced

Key Combination	Function
Ctrl+Space	Open Auto-Completion
Ctrl+K	Comment/Uncomment
Tab/Shift+Tab	Indent/Un-indent selected lines
Ctrl+Left/Right	Jump to previous/next word
Ctrl+Up/Down	Move line(s) up/down
Shift+Arrow Key	Select text
Ctrl+W	Select word under cursor
Ctrl+N	Jump to beginning of next line
Ctrl+T	Toggle upper/lower case
Ctrl+G	Reset file to version stored in git
Ctrl+B	Toggle inline git blame view
F7	Open menu
F12	Show readme document

FAQ

• What does affe mean?

  • affe is an acronym for A Full- Fledged Editor. Also, affe means "monkey" in German. Monkeys are cool.

• How to pronounce affe?

  • IPA: [ˈafə] (af like in "Muffin", fe like in "feather")

• Why not use vim/nano/...?

  • Their keyboard shortcuts are hard to remember: How do I exit Vim? and many of those editors lack proper syntax highlighting. And no, I don't want to install plugins for those basic features.

• Why not use a graphical editor?

  • Using a graphical editor is unnecessary overhead for quickly editing system config files. Also, it sucks to use a graphical editor on a remote server. A terminal-based editor is much more responsive while saving bandwidth and power on the client system.

• Why yet another text editor?

  • affe aims to be very user-friendly while still being a terminal-based text editor. It is possible to control affe completely mouse-driven so you can start right away. And keyboard shortcuts are designed to be intuitive.

• Which programming languages are supported for syntax highlighting?

  • affe uses the pygments library for syntax highlighting. This means that all languages and file formats supported by pygments (currently ~600) are also supported by affe.

• What are those blue lines right next to the scrollbar?

  • This is the git minimap. It indicates modified lines throughout the whole file. Pretty neat, huh?

• Why is affe not found when using sudo affe?

  • sudo does not inherit the user's PATH environment variable. Create a symlink: sudo ln -s $(which affe) /usr/local/bin/affe.

• Why is Ctrl+Arrow Down and Ctrl+Arrow Up not working?

  • This is a known issue on macOS. The Ctrl+Arrow Down and Ctrl+Arrow Up keybindings are reserved by the system for switching between spaces. You can change this in the system preferences: System Preferences > Keyboard > Shortcuts > Mission Control: Select the Mission Control and Program Windows options and uncheck them or change the keybindings to something else (e.g. Ctrl+Shift+Arrow Down and Ctrl+Shift+Arrow Up).

• Why is the Ctrl+Space auto-completion not working?

  • This is a known issue on macOS. The Ctrl+Space keybinding is reserved by the system for switching input sources. You can change this in the system preferences: System Preferences > Keyboard > Shortcuts > Input Sources: Select the Select the previous input source option and uncheck it or change the keybinding to something else (e.g. Ctrl+Shift+Space).

• The default blinking block cursor (█) feels wrong in an editor. Can it be changed to a line cursor (|)?

  • Yes, for most terminals this can be changed in the preferences. Look for a Cursor Shape option and change it accordingly.

• Why are all lines in my file marked as modified by git?

  • I bet your file uses CRLF line endings (Windows) instead of LF (everyone else). This confuses affe.

• Why are modified lines in my file not highlighted by git?

  • Is your file tracked by git? If yes, then your file probably uses an unsupported encoding. Check the output of this command: file <yourfile>.

• Why do I see weird ? characters all over the place?

  • Enable UTF-8 support by running the following command in the terminal: export LC_ALL=C.UTF-8

• How can I use affe as the default editor, e.g. for git commit messages?

  • Run the following command: git config --global core.editor "affe" and add export EDITOR=affe to your shell profile file (e.g. ~/.profile or ~/.zprofile).

Known Limitations

affe is primarily developed and tested on Ubuntu. Some features may not work as expected on other systems.

affe uses the awesome python-prompt-toolkit library, which offers great customizability at the cost of performance. On very large files (e.g. > 10,000 lines) some operations may feel sluggish. Also, startup time may be longer than expected. This performance impact is especially noticeable when trying to run affe (please don't) on low-end hardware (e.g. Raspberry Pi).

CPU usage is generally higher than one might expect for a terminal-based editor. This is mainly due to the usage of python-prompt-toolkit, but also caused by the convenience features that run continuously in the background:

• Update syntax highlighting
• Check for external file modifications
• Update git inline diff and minimap

Bonus

Congratulations! You have reached the end of this readme.

Here are two Easter eggs for you:

• Run affe chess.py to play a game of chess against the sunfish engine.
• Run affe <file>.paint to open a simple painting application.