{"id":15211109,"url":"https://gitlab.com/Syndamia/homelander","last_synced_at":"2025-10-03T03:30:25.244Z","repository":{"id":53862664,"uuid":"38381192","full_name":"Syndamia/homelander","owner":"Syndamia","description":"A tiny, good looking and dead simple zsh prompt","archived":false,"fork":false,"pushed_at":null,"size":null,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":null,"default_branch":"main","last_synced_at":"2025-01-17T16:27:02.293Z","etag":null,"topics":["bash","lightweight","simple","zsh","zsh theme","zsh-themes","zshell"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0+","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://gitlab.com/uploads/-/system/project/avatar/38381192/logo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-05T19:14:29.478Z","updated_at":"2023-03-03T07:04:27.587Z","dependencies_parsed_at":"2022-08-26T20:58:19.733Z","dependency_job_id":null,"html_url":"https://gitlab.com/Syndamia/homelander","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/Syndamia%2Fhomelander","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/Syndamia%2Fhomelander/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/Syndamia%2Fhomelander/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/Syndamia%2Fhomelander/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/owners/Syndamia","download_url":"https://gitlab.com/Syndamia/homelander/-/archive/main/homelander-main.zip","host":{"name":"gitlab.com","url":"https://gitlab.com","kind":"gitlab","repositories_count":4516918,"owners_count":6663,"icon_url":"https://github.com/gitlab.png","version":null,"created_at":"2022-05-30T11:31:42.605Z","updated_at":"2024-07-18T11:24:13.055Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/owners"}},"keywords":["bash","lightweight","simple","zsh","zsh theme","zsh-themes","zshell"],"created_at":"2024-09-28T08:04:53.651Z","updated_at":"2025-10-03T03:30:24.653Z","avatar_url":"https://gitlab.com/uploads/-/system/project/avatar/38381192/logo.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Homelander \u003cimg src=\"./img/logo.png\" height=\"29\" width=\"29\"\u003e\n\nA tiny, good looking and simple zsh prompt.\nThe goal is to simplify making your prompt, while also being as small as possible.\n\n`homelander.zsh` has the main logic, powering the theme, in 200 lines or less (with documentation), or your money back!  \n`homelander-sections.zsh` has prebuilt sections, you can not use it if you want.\n\n### Contents\n\n1. [Configuring](#configuring)\n   1. [Colors](#colors)\n   2. [Sections](#sections)\n   3. [Asynchronicity](#asynchronicity)\n2. [Installation](#installation)\n   1. [Manual](#manual)\n3. [Screenshots](#screenshots)\n\n## Configuring\n\nConfiguring your prompt is very much done the manual way, but homelander simplifies this process significantly.\n\nThe prompt to the left of your cursor is specified by the variable `PROMPT`, and the one on the right (edge of the screen) is specified by `RPROMPT`.\nThose variables are just specifically formatted character strings, surrounded in **single quotes** (`'`).\nMultiple lines are done by putting a `\\n` somewhere in `PROMPT` (or `RPROMPT`), all stuff afterwards are on a new line.\n\nEverything that isn't just static text, like the amount of background tasks or the current time, needs to be \"generated\" by a function.\nYou call a function in `PROMPT` (or `RPROMPT`) by adding\n\n```\n$(functionName parameter1 parameter2 ...)\n```\n\n### Colors\n\nQuite often you might want to add color to your text and surround it with some characters, like this:\n\n![](./img/username-pill.png)\n\nOr better yet, you might want to have multiple stuff next to each other, with separators and different colors:\n\n![](./img/multiple-pill.png)\n\nDoing this manually is a hassle, so homelander provides 3 functions that fill most needs (more detail in [homelander.zsh](./homelander.zsh)):\n\n- [`hl_cecho`](https://gitlab.com/Syndamia/homelander/-/blob/main/homelander.zsh#L89) takes three argument, foreground color code, background color code and a string.\n  The string has those exact colors set.  \n\n  Bad example:\n  ```\n  hl_cecho 223 66 kamen\n  ```\n  produces ![](./img/username-colored.png)\n\n- [`hl_cecho_caps`](https://gitlab.com/Syndamia/homelander/-/blob/main/homelander.zsh#L101) same as `hl_cecho`, however it allows for two characters at the ends (that I call caps),\n  which will be colored with swapped colors, effectively making a shape.  \n\n  Bad example:\n  ```\n  hl_cecho_caps 223 66 kamen  \n  ```\n  produces ![](./img/username-pill.png)\n\n- [`hl_concatsec`](https://gitlab.com/Syndamia/homelander/-/blob/main/homelander.zsh#L150) creates that line with multiple differently colored parts.\n  It takes information about the end caps, separator and then every part is in the same format,\n  foreground color, background color, text.\n  The only caveat is that if you want a separator to be the empty string, you'll have to use `\\b`.  \n\n  Bad example:\n  ```\n  hl_concatsec \\b  \\b  \\b  0   223 66 kamen   214 0 \"12:54\"   223 172 \n  ```\n  produces ![](./img/multiple-pill.png)\n\n### Sections\n\nHowever, we still need to generate some of those stuff too!\nThe username should change, depending on the logged in user, the time needs to change and so on.\n\nEach such piece of information is separated into it's own \"generator\" function, which will \"return\" (`echo -en`) the foreground color, background color and text, all ready to use.\nI call such functions (and all of the variables and helper functions they use) \"sections\".\n\nA proper example of how we would use `hl_concatsec` is:\n\n```\nhl_concatsec \\b  \\b  \\b  0   $(hl_user) $(hl_time) $(hl_distro_icon)\n```\n\nIt's important to note that we **mustn't** put quotes around the \"inner\" function calls!\nA wide variety of pre made sections exist in `homelander-sections.zsh`\n\nHomelander also provides the `lc_mode` function, which will return a successful exit code, when the terminal is running with a small amount of colors (like in a tty).\nOn all pre made sections, variable values for colors and characters are chosen depending on that, so your setup will look fine even on such terminals.\n\n### Asynchronicity\n\nThe final problem we have is that of sections like the clock, which need to be updated all the time, and git information sections, since git can take a while to show the data and nobody wants to wait for their theme.\n\nHomelander provides 2 functions for that purpose:\n\n- [`hl_run_async`](https://gitlab.com/Syndamia/homelander/-/blob/main/homelander.zsh#L116) which will run a function (without parameters) in the background and output it's result in a temporary file\n- [`hl_run_async_cont`](https://gitlab.com/Syndamia/homelander/-/blob/main/homelander.zsh#L133) which endlessly reruns a function by some given period, and pass it the last result\n\nHowever, those functions aren't used in `PROMPT`, they're used in a function called `hl_hooks`.\nThis function should be filled in your own `.zshrc`.\n\nFinally, since it might not be obvious how is best for a section to be ran in the background, all pre made sections in `homelander-sections.zsh` that require background operation have a `functionName_async` function, which sets that up and doesn't require any arguments.\n\nAll in all, for our clock to work, all we need is:\n\n```\nhl_hooks() {\n    hl_time_async\n}\n```\n\n### Putting it all together\n\nThe configuration in your `.zshrc` (without the sourcing of homelander):\n\n```\nexport PROMPT='$(hl_concatsec \\b  \\b  \\b  0 $(hl_user) $(hl_time) $(hl_distro_icon)) $(hl_cecho $(hl_precursor)) '\nexport RPROMPT=''\n\nhl_hooks() {\n    hl_time_async\n    hl_precursor_async\n}\n```\n\nproduces:\n\n![](./img/leftprompt-finished.png)\n\nWhere `hl_precursor` is shown as a double arrow (as in the screenshot) normally, and shows a specific character when in a git repository.\n\n## Installation\n\n### Manual\n\n1. Download the `homelander.zsh` file\n```bash\ncurl https://gitlab.com/Syndamia/homelander/-/raw/main/homelander.zsh -o homelander.zsh\n```\n\n2. Source it in your `.zshrc` or in a running shell (remember to change the path if you downloaded it elsewhere)\n```bash\nsource ~/homelander.zsh\n```\n\n**IMPORTANT:** If you want to also use the pre made sections, you'll have to do both steps for `homelander-sections.zsh`.  \n\nAlternatively\n\n1. Clone the repository\n```bash\ngit clone https://gitlab.com/Syndamia/homelander.git\n```\n\n2. Source the files you want in your `.zshrc`\n\n## Screenshots\n\n![](./img/screenshot.png)\n\n*Normal mode with Terminator as terminal emulator and MesloLGS NF font*\n\n![](./img/screenshot-lc.png)\n\n*Low colour mode in a virtual terminal with font Lat15-Fixed16.psf.gz (default on Debian)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/gitlab.com%2FSyndamia%2Fhomelander","html_url":"https://awesome.ecosyste.ms/projects/gitlab.com%2FSyndamia%2Fhomelander","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/gitlab.com%2FSyndamia%2Fhomelander/lists"}