From 1dc9e1fc902d7e0af4b23e9bd87806cfd18adea6 Mon Sep 17 00:00:00 2001
From: Hanashiko <hlichisper@gmail.com>
Date: Fri, 23 May 2025 23:36:50 +0300
Subject: [PATCH] docs(profiles): improved documentation

---
 plugins/profiles/README.md | 52 ++++++++++++++++++++++++++++++--------
 1 file changed, 41 insertions(+), 11 deletions(-)

diff --git a/plugins/profiles/README.md b/plugins/profiles/README.md
index 5aa1918e2..1dbc4e692 100644
--- a/plugins/profiles/README.md
+++ b/plugins/profiles/README.md
@@ -1,25 +1,55 @@
 # profiles plugin
 
-This plugin allows you to create separate configuration files for zsh based
-on your long hostname (including the domain).
+The `profiles` plugin allows you to automatically load machine-specific Zsh configuration files based on your fully qualified hostname.
+This is especially useful if you work across multiple systems (e.g. personal laptop, work server, containers) and need different aliases, environament variables, or behaveors on each.
 
-To use it, add profiles to the plugins array of your zshrc file:
+To use it, add `profiles` to the plugins array of your zshrc file:
 
 ```sh
 plugins=(... profiles)
 ```
 
-It takes your `$HOST` variable and looks for files named according to the
-domain parts in `$ZSH_CUSTOM/profiles/` directory.
-
-For example, for `HOST=host.domain.com`, it will try to load the following files,
-in this order:
-
+## How It Works
+The plugin inspects the `$HOST` environament variable and attempts to source configuration files based on its domain hierarchy.
+For a hostname like:
+```bash
+HOST=host.domain.com
+```
+It fill try to source the following files in order of generality -> specificity:
 ```text
 $ZSH_CUSTOM/profiles/com
 $ZSH_CUSTOM/profiles/domain.com
 $ZSH_CUSTOM/profiles/host.domain.com
 ```
+Each files is sourced if it exists. More specific files override earlier general settings.
 
-This means that if there are conflicting settings on those files, the one to take
-precedence will be the last applied, i.e. the one in host.domain.com.
+## Directory Structure
+Create your profile files under:
+```bash
+$ZSH_CUSTOM/profiles/
+```
+Example structure:
+```bash
+~/.oh-my-zsh/custom/
+├── plugins/
+│   └── profiles/
+│       └── profiles.plugin.zsh
+└── profiles/
+    ├── com
+    ├── domain.com
+    └── host.domain.com
+```
+
+## Example
+For `HOST=dev.internal.example.com`, the plugin will attempts to load:
+```bash
+$ZSH_CUSTOM/profiles/com
+$ZSH_CUSTOM/profiles/example.com
+$ZSH_CUSTOM/profiles/internal.example.com
+$ZSH_CUSTOM/profiles/dev.internal.example.com
+```
+
+## Tips
+ - Each profile file should contain valid Zsh code (e.g., `export`, `alias`, etc.).
+ - Later (more specific) profiles override settings from earlier (more general) ones.
+ - You can use this for environment-specific variables, host-specific tool paths, aliases, or functions.