fix: option in the settings, documentation

andriy-chernov · andrinoff · commit 26b80fb02f07 · 2026-05-07T13:05:43.000+04:00
Signed-off-by: drew &lt;me@andrinoff.com&gt;
diff --git a/config/config.go b/config/config.go
@@ -91,6 +91,7 @@ type Config struct {
 	HideTips             bool          `json:"hide_tips,omitempty"`
 	DisableNotifications bool          `json:"disable_notifications,omitempty"`
 	EnableSplitPane      bool          `json:"enable_split_pane,omitempty"`
+	EnableThreaded       bool          `json:"enable_threaded,omitempty"`
 	Theme                string        `json:"theme,omitempty"`
 	MailingLists         []MailingList `json:"mailing_lists,omitempty"`
 	DateFormat           string        `json:"date_format,omitempty"`
diff --git a/config/folder_cache.go b/config/folder_cache.go
@@ -204,14 +204,22 @@ func LoadFolderEmailHeaders(folderName string) ([]threading.EmailHeader, error)
 	return headers, nil
 }
 
-func IsFolderThreaded(folderName string) bool {
+// IsFolderThreaded returns the threading state for a folder. If the user has
+// explicitly toggled threading for this folder, that override is returned.
+// Otherwise defaultEnabled (from Config.EnableThreaded) is used.
+func IsFolderThreaded(folderName string, defaultEnabled bool) bool {
 	cache, err := LoadFolderCache()
 	if err != nil || cache.ThreadedFolders == nil {
-		return false
+		return defaultEnabled
 	}
-	return cache.ThreadedFolders[folderName]
+	v, ok := cache.ThreadedFolders[folderName]
+	if !ok {
+		return defaultEnabled
+	}
+	return v
 }
 
+// SetFolderThreaded stores an explicit per-folder threading override.
 func SetFolderThreaded(folderName string, threaded bool) error {
 	cache, err := LoadFolderCache()
 	if err != nil {
@@ -220,11 +228,7 @@ func SetFolderThreaded(folderName string, threaded bool) error {
 	if cache.ThreadedFolders == nil {
 		cache.ThreadedFolders = make(map[string]bool)
 	}
-	if threaded {
-		cache.ThreadedFolders[folderName] = true
-	} else {
-		delete(cache.ThreadedFolders, folderName)
-	}
+	cache.ThreadedFolders[folderName] = threaded
 	return SaveFolderCache(cache)
 }
 
diff --git a/docs/docs/Features/Keybinds.md b/docs/docs/Features/Keybinds.md
@@ -22,9 +22,12 @@ Plain text, not encrypted. Edit with any text editor. Restart matcha to apply ch
   },
   "inbox": {
     "visual_mode": "v",
+    "toggle_threaded": "T",
     "delete": "d",
     "archive": "a",
     "refresh": "r",
+    "search": "/",
+    "filter": "f",
     "open": "enter",
     "next_tab": "l",
     "prev_tab": "h"
diff --git a/docs/docs/Features/THREADED_VIEW.md b/docs/docs/Features/THREADED_VIEW.md
@@ -0,0 +1,82 @@
+---
+title: Threaded View
+sidebar_position: 13
+---
+
+# Threaded Conversation View
+
+Matcha can group related emails into conversations using the JWZ threading
+algorithm (the same approach used by mutt and other classic mail clients).
+Replies, forwards, and quoted threads collapse under their root message so an
+inbox of 200 individual messages can render as 30 conversations.
+
+## Enabling threaded view
+
+There are three ways to control threading:
+
+### 1. Settings menu (global default)
+
+- Press `Esc` from the inbox to open the main menu.
+- Open **Settings** → **General**.
+- Toggle **Threaded Conversation View** to ON.
+
+This sets the default for every folder. New folders without an explicit
+override inherit this default immediately.
+
+### 2. Configuration file
+
+Edit `~/.config/matcha/config.json` and add:
+
+```json
+{
+  "enable_threaded": true
+}
+```
+
+### 3. Keybind (per-folder override)
+
+Press `T` (configurable as `inbox.toggle_threaded` in `keybinds.json`) from any
+inbox view to toggle threading **for the current folder only**. The override is
+persisted in the folder cache and survives restarts.
+
+A per-folder override always wins over the global default. To return a folder
+to the default, toggle it back to match the default value.
+
+## Using threaded view
+
+When threading is enabled the email list shows the root message of each
+conversation with a count of replies. The default state is collapsed.
+
+| Key      | Action                                  |
+| -------- | --------------------------------------- |
+| `T`      | Toggle threaded view for the folder     |
+| `enter`  | Open the focused message                |
+| `space`  | Expand or collapse the focused thread   |
+| `j`/`k`  | Navigate threads or messages within     |
+
+Visual mode (`v`), delete (`d`), archive (`a`), and the other inbox keybinds
+behave the same as in flat view — operations applied to a collapsed thread
+target the root message; expand the thread first to act on a single reply.
+
+## How threading works
+
+Matcha threads emails entirely on the client. Threading uses:
+
+1. `Message-ID`, `In-Reply-To`, and `References` headers (RFC 5322).
+2. A subject-based fallback that strips `Re:`, `Fwd:`, and locale-specific
+   prefixes when reply headers are missing.
+
+Threading is recomputed whenever the email cache changes for a folder, so new
+mail slots into existing conversations without a manual refresh.
+
+## Per-folder overrides
+
+The setting is split into two layers:
+
+- **Global default** — `Config.EnableThreaded` in `config.json`.
+- **Per-folder override** — stored in `folder_cache.json` under
+  `threaded_folders`. Only folders the user has explicitly toggled appear here.
+
+If you change the global default in settings, every folder without an override
+flips to the new default on the next render. Folders with an override keep
+their explicit value until toggled again.
diff --git a/i18n/locales/ar.json b/i18n/locales/ar.json
@@ -151,6 +151,7 @@
       "hide_tips": "إخفاء النصائح السياقية",
       "disable_notifications": "تعطيل الإشعارات",
       "enable_split_pane": "عرض مقسم",
+      "enable_threaded": "عرض المحادثات",
       "date_format": "تنسيق التاريخ",
       "language": "اللغة",
       "signature": "تعديل التوقيع",
diff --git a/i18n/locales/de.json b/i18n/locales/de.json
@@ -147,6 +147,7 @@
       "hide_tips": "Kontextuelle Tipps Ausblenden",
       "disable_notifications": "Benachrichtigungen Deaktivieren",
       "enable_split_pane": "Geteilte Ansicht",
+      "enable_threaded": "Konversations-Threads",
       "date_format": "Datumsformat",
       "language": "Sprache",
       "signature": "Signatur Bearbeiten",
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
@@ -147,6 +147,7 @@
       "hide_tips": "Hide Contextual Tips",
       "disable_notifications": "Disable Notifications",
       "enable_split_pane": "Split Pane View",
+      "enable_threaded": "Threaded Conversation View",
       "date_format": "Date Format",
       "language": "Language",
       "signature": "Edit Signature",
diff --git a/i18n/locales/es.json b/i18n/locales/es.json
@@ -147,6 +147,7 @@
       "hide_tips": "Ocultar Consejos Contextuales",
       "disable_notifications": "Deshabilitar Notificaciones",
       "enable_split_pane": "Vista dividida",
+      "enable_threaded": "Vista de conversación",
       "date_format": "Formato de Fecha",
       "language": "Idioma",
       "signature": "Editar Firma",
diff --git a/i18n/locales/fr.json b/i18n/locales/fr.json
@@ -147,6 +147,7 @@
       "hide_tips": "Masquer les Conseils Contextuels",
       "disable_notifications": "Désactiver les Notifications",
       "enable_split_pane": "Vue divisée",
+      "enable_threaded": "Vue par conversation",
       "date_format": "Format de Date",
       "language": "Langue",
       "signature": "Modifier la Signature",
diff --git a/i18n/locales/ja.json b/i18n/locales/ja.json
@@ -145,6 +145,7 @@
       "hide_tips": "コンテキストヒントを非表示",
       "disable_notifications": "通知を無効化",
       "enable_split_pane": "分割ビュー",
+      "enable_threaded": "スレッド表示",
       "date_format": "日付形式",
       "language": "言語",
       "signature": "署名を編集",
diff --git a/i18n/locales/pl.json b/i18n/locales/pl.json
@@ -151,6 +151,7 @@
       "hide_tips": "Ukryj Wskazówki Kontekstowe",
       "disable_notifications": "Wyłącz Powiadomienia",
       "enable_split_pane": "Widok podzielony",
+      "enable_threaded": "Widok wątków",
       "date_format": "Format Daty",
       "language": "Język",
       "signature": "Edytuj Podpis",
diff --git a/i18n/locales/pt.json b/i18n/locales/pt.json
@@ -147,6 +147,7 @@
       "hide_tips": "Ocultar Dicas Contextuais",
       "disable_notifications": "Desativar Notificações",
       "enable_split_pane": "Vista dividida",
+      "enable_threaded": "Vista de conversação",
       "date_format": "Formato de Data",
       "language": "Idioma",
       "signature": "Editar Assinatura",
diff --git a/i18n/locales/ru.json b/i18n/locales/ru.json
@@ -151,6 +151,7 @@
       "hide_tips": "Скрыть Контекстные Подсказки",
       "disable_notifications": "Отключить Уведомления",
       "enable_split_pane": "Разделённый вид",
+      "enable_threaded": "Просмотр беседами",
       "date_format": "Формат Даты",
       "language": "Язык",
       "signature": "Редактировать Подпись",
diff --git a/i18n/locales/uk.json b/i18n/locales/uk.json
@@ -149,6 +149,7 @@
       "hide_tips": "Приховати контекстні підказки",
       "disable_notifications": "Вимкнути сповіщення",
       "enable_split_pane": "Розділений вигляд",
+      "enable_threaded": "Перегляд розмов",
       "date_format": "Формат дати",
       "language": "Мова",
       "signature": "Редагувати підпис",
diff --git a/i18n/locales/zh.json b/i18n/locales/zh.json
@@ -145,6 +145,7 @@
       "hide_tips": "隐藏上下文提示",
       "disable_notifications": "禁用通知",
       "enable_split_pane": "分屏视图",
+      "enable_threaded": "会话视图",
       "date_format": "日期格式",
       "language": "语言",
       "signature": "编辑签名",
diff --git a/main.go b/main.go
@@ -465,6 +465,7 @@ func (m *mainModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 		m.folderInbox = tui.NewFolderInbox(cachedFolders, m.config.Accounts)
 		m.folderInbox.SetDateFormat(m.config.GetDateFormat())
+		m.folderInbox.SetDefaultThreaded(m.config.EnableThreaded)
 		// Use cached INBOX emails for instant display (memory first, then disk)
 		if cached, ok := m.folderEmails["INBOX"]; ok && len(cached) > 0 {
 			m.folderInbox.SetEmails(cached, m.config.Accounts)
@@ -1018,6 +1019,9 @@ func (m *mainModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				log.Printf("config reload: %v", err)
 			}
 		}
+		if m.folderInbox != nil {
+			m.folderInbox.SetDefaultThreaded(m.config.EnableThreaded)
+		}
 		return m, nil
 
 	case tui.LanguageChangedMsg:
diff --git a/tui/folder_inbox.go b/tui/folder_inbox.go
@@ -133,6 +133,13 @@ func (m *FolderInbox) SetDateFormat(layout string) {
 	}
 }
 
+// SetDefaultThreaded propagates the global default threading toggle.
+func (m *FolderInbox) SetDefaultThreaded(v bool) {
+	if m.inbox != nil {
+		m.inbox.SetDefaultThreaded(v)
+	}
+}
+
 // NewFolderInbox creates a new FolderInbox with the given folders and accounts.
 func NewFolderInbox(folders []string, accounts []config.Account) *FolderInbox {
 	folders = sortFolders(folders)
diff --git a/tui/inbox.go b/tui/inbox.go
@@ -322,6 +322,7 @@ type Inbox struct {
 	searchResults      []fetcher.Email
 	threaded           map[string]bool
 	expanded           map[string]bool
+	defaultThreaded    bool
 
 	// Visual mode state (Vim-style multi-select)
 	visualMode     bool              // Whether visual mode is active
@@ -754,6 +755,16 @@ func (m *Inbox) folderKey() string {
 	return string(m.mailbox)
 }
 
+// SetDefaultThreaded sets the global default threading state used when no
+// per-folder override exists. Pass Config.EnableThreaded.
+func (m *Inbox) SetDefaultThreaded(v bool) {
+	m.defaultThreaded = v
+	// Drop the in-memory cache so the new default takes effect for folders
+	// without an explicit override on the next render.
+	m.threaded = nil
+	m.expanded = nil
+}
+
 func (m *Inbox) isThreaded() bool {
 	if m.threaded == nil {
 		m.threaded = make(map[string]bool)
@@ -763,7 +774,7 @@ func (m *Inbox) isThreaded() bool {
 	}
 	key := m.folderKey()
 	if _, ok := m.threaded[key]; !ok {
-		m.threaded[key] = config.IsFolderThreaded(key)
+		m.threaded[key] = config.IsFolderThreaded(key, m.defaultThreaded)
 	}
 	return m.threaded[key]
 }
diff --git a/tui/settings_general.go b/tui/settings_general.go
@@ -23,6 +23,7 @@ func (m *Settings) buildGeneralOptions() []generalOption {
 		{"settings_general.hide_tips", onOff(m.cfg.HideTips), "Hide helpful hints displayed at the bottom of the screen.", false, ""},
 		{"settings_general.disable_notifications", onOff(m.cfg.DisableNotifications), "Turn off desktop notifications for new mail.", false, ""},
 		{"settings_general.enable_split_pane", onOff(m.cfg.EnableSplitPane), "View inbox and email side-by-side.", false, ""},
+		{"settings_general.enable_threaded", onOff(m.cfg.EnableThreaded), "Group emails into conversations by reply chain. Per-folder overrides are kept.", false, ""},
 		{"settings_general.date_format", getDateFormatLabel(m.cfg.DateFormat), "Change how dates and times are displayed.", false, ""},
 		{"settings_general.language", getLanguageLabel(m.cfg.GetLanguage()), "Change the interface language. Changes apply instantly.", false, ""},
 		{"settings_general.signature", getSignatureStatus(), "Configure the global signature appended to your outgoing emails.", false, ""},
@@ -86,7 +87,11 @@ func (m *Settings) updateGeneral(msg tea.KeyPressMsg) (tea.Model, tea.Cmd) {
 				m.cfg.EnableSplitPane = !m.cfg.EnableSplitPane
 				_ = config.SaveConfig(m.cfg)
 				saved = true
-			case 4: // Date Format
+			case 4: // Threaded Conversation View
+				m.cfg.EnableThreaded = !m.cfg.EnableThreaded
+				_ = config.SaveConfig(m.cfg)
+				saved = true
+			case 5: // Date Format
 				switch m.cfg.DateFormat {
 				case config.DateFormatEU:
 					m.cfg.DateFormat = config.DateFormatUS
@@ -97,7 +102,7 @@ func (m *Settings) updateGeneral(msg tea.KeyPressMsg) (tea.Model, tea.Cmd) {
 				}
 				_ = config.SaveConfig(m.cfg)
 				saved = true
-			case 5: // Language
+			case 6: // Language
 				// Cycle through available languages
 				langs := i18n.LanguageCodes()
 				currentLang := m.cfg.GetLanguage()
@@ -118,7 +123,7 @@ func (m *Settings) updateGeneral(msg tea.KeyPressMsg) (tea.Model, tea.Cmd) {
 					func() tea.Msg { return ConfigSavedMsg{} },
 					func() tea.Msg { return LanguageChangedMsg{} },
 				)
-			case 6: // Edit Signature
+			case 7: // Edit Signature
 				if msg.String() == "enter" || msg.String() == "right" || msg.String() == "l" {
 					return m, func() tea.Msg { return GoToSignatureEditorMsg{} }
 				}
