2015-12-17 07:44:19 -05:00
|
|
|
<div align="center">
|
2018-01-01 07:58:41 -05:00
|
|
|
<a href="https://github.com/zimfw/zimfw">
|
2021-01-14 09:29:16 -05:00
|
|
|
<img width="600" src="https://zimfw.github.io/images/zimfw-banner@2.jpg">
|
2015-12-17 07:44:19 -05:00
|
|
|
</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
2015-12-15 00:12:17 -05:00
|
|
|
What is Zim?
|
|
|
|
|
------------
|
2019-01-22 19:40:43 -05:00
|
|
|
Zim is a Zsh configuration framework with [blazing speed] and modular extensions.
|
2015-12-17 08:06:26 -05:00
|
|
|
|
2021-08-08 21:44:37 -04:00
|
|
|
Zim bundles useful [modules], a wide variety of [themes], and plenty of
|
|
|
|
|
customizability without compromising on speed.
|
2015-12-15 00:12:17 -05:00
|
|
|
|
|
|
|
|
What does Zim offer?
|
2021-08-08 21:44:37 -04:00
|
|
|
--------------------
|
2015-12-16 18:00:14 -05:00
|
|
|
Below is a brief showcase of Zim's features.
|
2015-12-15 00:12:17 -05:00
|
|
|
|
2015-12-18 13:41:02 -05:00
|
|
|
### Speed
|
2021-08-08 21:44:37 -04:00
|
|
|
<a href="https://github.com/zimfw/zimfw/wiki/Speed">
|
|
|
|
|
<img src="https://zimfw.github.io/images/results.svg">
|
|
|
|
|
</a>
|
2015-12-18 13:34:24 -05:00
|
|
|
|
2021-08-08 21:44:37 -04:00
|
|
|
For more details, see [this wiki entry][blazing speed].
|
2015-12-18 11:44:57 -05:00
|
|
|
|
2021-08-08 21:44:37 -04:00
|
|
|
### Modules
|
2015-12-18 11:44:57 -05:00
|
|
|
|
2021-08-08 21:44:37 -04:00
|
|
|
Zim has many [modules available][modules]. Enable as many or as few as you'd like.
|
2015-12-15 00:12:17 -05:00
|
|
|
|
2021-08-08 21:44:37 -04:00
|
|
|
### Themes
|
2015-12-15 00:12:17 -05:00
|
|
|
|
2021-08-08 21:44:37 -04:00
|
|
|
To preview some of the available themes, check the [themes page][themes].
|
2015-12-15 00:12:17 -05:00
|
|
|
|
2021-08-10 11:38:01 -04:00
|
|
|
### Degit
|
|
|
|
|
|
|
|
|
|
Install modules without requiring `git` using our degit tool. It's faster and
|
|
|
|
|
lighter. See the [zmodule](#zmodule) usage below.
|
|
|
|
|
|
2015-12-15 00:12:17 -05:00
|
|
|
Installation
|
|
|
|
|
------------
|
2019-01-10 19:59:04 -05:00
|
|
|
Installing Zim is easy:
|
2015-12-15 00:12:17 -05:00
|
|
|
|
2019-01-22 19:40:43 -05:00
|
|
|
* With curl:
|
|
|
|
|
|
2020-01-02 13:05:53 -05:00
|
|
|
curl -fsSL https://raw.githubusercontent.com/zimfw/install/master/install.zsh | zsh
|
2019-01-22 19:40:43 -05:00
|
|
|
|
|
|
|
|
* With wget:
|
|
|
|
|
|
2020-01-02 13:05:53 -05:00
|
|
|
wget -nv -O - https://raw.githubusercontent.com/zimfw/install/master/install.zsh | zsh
|
2015-12-15 00:12:17 -05:00
|
|
|
|
2021-07-01 18:58:49 -04:00
|
|
|
Open a new terminal and you're done. Enjoy your Zsh IMproved! Take some time to
|
2021-08-08 21:44:37 -04:00
|
|
|
tweak your `~/.zshrc` file, and to also check the available [modules] and [themes]
|
2021-07-01 18:58:49 -04:00
|
|
|
you can add to your `~/.zimrc`.
|
2015-12-15 00:12:17 -05:00
|
|
|
|
2021-07-01 18:58:49 -04:00
|
|
|
<details>
|
|
|
|
|
<summary>Prefer to install manually?</summary>
|
Add a plugin mechanism \o/
This is a major change, where Zsh modules/plugins are not git submodules
in the Zim repo anymore, but customized and installed separately as
individual repositories. The discussion about this started more than 2
years ago in #88. Closes #299.
This will allow contributors' modules to live in their own repositories.
See #33, #138, #262, #281, #324.
The current code has what, up to this point, I considered to be the best
balance between simplicity, execution speed and number of files.
One measured decision was to make the initialization of modules depend
only on the `':zim' modules` style, keeping it as fast as possible.
The `':zim:module' module` style is used to install, update and clean
the modules, all operations that happen after the user got his
as-blazing-fast-possible shell prompt.
Even though I didn't care much about making install or update fast,
`xargs` has a nice feature of allowing commands to be executed in
parallel with `-P`. I took advantage of that.
I've also worked on making the `zimfw` utility give the user some nice
(while still minimalistic) output. Also I'm suggesting this as the new
name for the `zmanage` tool, since `zimfw` does not shadow the `zim`
wiki tool.
2019-01-07 18:25:34 -05:00
|
|
|
|
2019-12-04 07:22:17 -05:00
|
|
|
### Manual installation
|
|
|
|
|
|
2020-06-11 22:13:55 -04:00
|
|
|
1. Set Zsh as the default shell:
|
2019-12-04 07:22:17 -05:00
|
|
|
|
2020-06-11 22:13:55 -04:00
|
|
|
chsh -s $(which zsh)
|
2019-12-04 07:22:17 -05:00
|
|
|
|
2021-07-01 18:58:49 -04:00
|
|
|
2. Prepend the lines in the following templates to the respective dot files:
|
|
|
|
|
* [~/.zshenv](https://raw.githubusercontent.com/zimfw/install/master/src/templates/zshenv)
|
|
|
|
|
* [~/.zshrc](https://raw.githubusercontent.com/zimfw/install/master/src/templates/zshrc)
|
|
|
|
|
* [~/.zlogin](https://raw.githubusercontent.com/zimfw/install/master/src/templates/zlogin)
|
|
|
|
|
* [~/.zimrc](https://raw.githubusercontent.com/zimfw/install/master/src/templates/zimrc)
|
2019-12-04 07:22:17 -05:00
|
|
|
|
2020-06-11 22:13:55 -04:00
|
|
|
3. Copy https://github.com/zimfw/zimfw/releases/latest/download/zimfw.zsh to
|
|
|
|
|
`~/.zim/zimfw.zsh`.
|
|
|
|
|
|
|
|
|
|
4. Install the modules defined in `~/.zimrc` and build the initialization scripts:
|
2019-12-04 07:22:17 -05:00
|
|
|
|
2020-06-11 22:13:55 -04:00
|
|
|
zsh ~/.zim/zimfw.zsh install
|
2019-12-04 07:22:17 -05:00
|
|
|
|
2021-07-01 18:58:49 -04:00
|
|
|
</details>
|
|
|
|
|
|
2019-12-01 16:00:47 -05:00
|
|
|
Usage
|
|
|
|
|
-----
|
2016-09-05 18:36:44 -04:00
|
|
|
|
2019-12-01 16:00:47 -05:00
|
|
|
### zmodule
|
2016-09-05 18:36:44 -04:00
|
|
|
|
2021-08-10 11:38:01 -04:00
|
|
|
<pre>Usage: <b>zmodule</b> <url> [<b>-n</b>|<b>--name</b> <module_name>] [options]
|
2016-09-05 18:36:44 -04:00
|
|
|
|
2021-08-10 11:38:01 -04:00
|
|
|
Add <b>zmodule</b> calls to your <b>~/.zimrc</b> file to define the modules to be initialized. The modules are
|
2020-05-02 19:47:38 -04:00
|
|
|
initialized in the same order they are defined.
|
2016-09-05 18:36:44 -04:00
|
|
|
|
2020-10-11 13:24:01 -04:00
|
|
|
<url> Module absolute path or repository URL. The following URL formats
|
2021-08-10 11:38:01 -04:00
|
|
|
are equivalent: <b>name</b>, <b>zimfw/name</b>, <b>https://github.com/zimfw/name.git</b>.
|
|
|
|
|
<b>-n</b>|<b>--name</b> <module_name> Set a custom module name. Default: the last component in the <url>.
|
|
|
|
|
Use slashes inside the name to organize the module into subdirecto-
|
|
|
|
|
ries.
|
Add a plugin mechanism \o/
This is a major change, where Zsh modules/plugins are not git submodules
in the Zim repo anymore, but customized and installed separately as
individual repositories. The discussion about this started more than 2
years ago in #88. Closes #299.
This will allow contributors' modules to live in their own repositories.
See #33, #138, #262, #281, #324.
The current code has what, up to this point, I considered to be the best
balance between simplicity, execution speed and number of files.
One measured decision was to make the initialization of modules depend
only on the `':zim' modules` style, keeping it as fast as possible.
The `':zim:module' module` style is used to install, update and clean
the modules, all operations that happen after the user got his
as-blazing-fast-possible shell prompt.
Even though I didn't care much about making install or update fast,
`xargs` has a nice feature of allowing commands to be executed in
parallel with `-P`. I took advantage of that.
I've also worked on making the `zimfw` utility give the user some nice
(while still minimalistic) output. Also I'm suggesting this as the new
name for the `zmanage` tool, since `zimfw` does not shadow the `zim`
wiki tool.
2019-01-07 18:25:34 -05:00
|
|
|
|
2020-01-15 12:35:30 -05:00
|
|
|
Repository options:
|
2021-08-10 11:38:01 -04:00
|
|
|
<b>-b</b>|<b>--branch</b> <branch_name> Use specified branch when installing and updating the module.
|
|
|
|
|
Overrides the tag option. Default: the repository's default branch.
|
|
|
|
|
<b>-t</b>|<b>--tag</b> <tag_name> Use specified tag when installing and updating the module.
|
2020-10-11 13:24:01 -04:00
|
|
|
Overrides the branch option.
|
2021-08-10 11:38:01 -04:00
|
|
|
<b>-u</b>|<b>--use</b> <<b>git</b>|<b>degit</b>> Install and update the module using the defined tool. Default is
|
|
|
|
|
defined by <b>zstyle ':zim:zmodule' use '</b><<b>git</b>|<b>degit</b>><b>'</b>, or <b>git</b> if none
|
|
|
|
|
is provided.
|
|
|
|
|
<b>git</b> requires git to be installed. Local changes are preserved during
|
|
|
|
|
updates.
|
|
|
|
|
<b>degit</b> requires curl or wget, and currently only works with GitHub
|
|
|
|
|
URLs. Modules install faster and take less disk space. Local changes
|
|
|
|
|
are lost during updates. Git submodules are not supported.
|
|
|
|
|
<b>-z</b>|<b>--frozen</b> Don't install or update the module.
|
Add a plugin mechanism \o/
This is a major change, where Zsh modules/plugins are not git submodules
in the Zim repo anymore, but customized and installed separately as
individual repositories. The discussion about this started more than 2
years ago in #88. Closes #299.
This will allow contributors' modules to live in their own repositories.
See #33, #138, #262, #281, #324.
The current code has what, up to this point, I considered to be the best
balance between simplicity, execution speed and number of files.
One measured decision was to make the initialization of modules depend
only on the `':zim' modules` style, keeping it as fast as possible.
The `':zim:module' module` style is used to install, update and clean
the modules, all operations that happen after the user got his
as-blazing-fast-possible shell prompt.
Even though I didn't care much about making install or update fast,
`xargs` has a nice feature of allowing commands to be executed in
parallel with `-P`. I took advantage of that.
I've also worked on making the `zimfw` utility give the user some nice
(while still minimalistic) output. Also I'm suggesting this as the new
name for the `zmanage` tool, since `zimfw` does not shadow the `zim`
wiki tool.
2019-01-07 18:25:34 -05:00
|
|
|
|
2020-01-15 12:35:30 -05:00
|
|
|
Initialization options:
|
2021-08-10 11:38:01 -04:00
|
|
|
<b>-f</b>|<b>--fpath</b> <path> Add specified path to fpath. The path is relative to the module
|
|
|
|
|
root directory. Default: <b>functions</b>, if the subdirectory exists.
|
|
|
|
|
<b>-a</b>|<b>--autoload</b> <func_name> Autoload specified function. Default: all valid names inside the
|
|
|
|
|
module's specified fpath paths.
|
|
|
|
|
<b>-s</b>|<b>--source</b> <file_path> Source specified file. The file path is relative to the module root
|
|
|
|
|
directory. Default: <b>init.zsh</b>, if the <b>functions</b> subdirectory also
|
2021-03-19 19:44:53 -04:00
|
|
|
exists, or the file with largest size matching
|
2021-08-10 11:38:01 -04:00
|
|
|
<b>{init.zsh,module_name.{zsh,plugin.zsh,zsh-theme,sh}}</b>, if any exist.
|
|
|
|
|
<b>-c</b>|<b>--cmd</b> <command> Execute specified command. Occurrences of the <b>{}</b> placeholder in the
|
2020-10-11 13:24:01 -04:00
|
|
|
command are substituted by the module root directory path.
|
2021-08-10 11:38:01 -04:00
|
|
|
I.e., <b>-s 'script.zsh'</b> and <b>-c 'source {}/script.zsh'</b> are equivalent.
|
|
|
|
|
<b>-d</b>|<b>--disabled</b> Don't initialize or uninstall the module.
|
2020-05-02 19:47:38 -04:00
|
|
|
</pre>
|
Add a plugin mechanism \o/
This is a major change, where Zsh modules/plugins are not git submodules
in the Zim repo anymore, but customized and installed separately as
individual repositories. The discussion about this started more than 2
years ago in #88. Closes #299.
This will allow contributors' modules to live in their own repositories.
See #33, #138, #262, #281, #324.
The current code has what, up to this point, I considered to be the best
balance between simplicity, execution speed and number of files.
One measured decision was to make the initialization of modules depend
only on the `':zim' modules` style, keeping it as fast as possible.
The `':zim:module' module` style is used to install, update and clean
the modules, all operations that happen after the user got his
as-blazing-fast-possible shell prompt.
Even though I didn't care much about making install or update fast,
`xargs` has a nice feature of allowing commands to be executed in
parallel with `-P`. I took advantage of that.
I've also worked on making the `zimfw` utility give the user some nice
(while still minimalistic) output. Also I'm suggesting this as the new
name for the `zmanage` tool, since `zimfw` does not shadow the `zim`
wiki tool.
2019-01-07 18:25:34 -05:00
|
|
|
|
2019-12-01 16:00:47 -05:00
|
|
|
### zimfw
|
2016-09-05 18:36:44 -04:00
|
|
|
|
2020-01-15 12:35:30 -05:00
|
|
|
Added new modules to `~/.zimrc`? Run `zimfw install`.
|
2016-09-05 18:36:44 -04:00
|
|
|
|
2020-01-15 12:35:30 -05:00
|
|
|
Removed modules from `~/.zimrc`? Run `zimfw uninstall`.
|
Add a plugin mechanism \o/
This is a major change, where Zsh modules/plugins are not git submodules
in the Zim repo anymore, but customized and installed separately as
individual repositories. The discussion about this started more than 2
years ago in #88. Closes #299.
This will allow contributors' modules to live in their own repositories.
See #33, #138, #262, #281, #324.
The current code has what, up to this point, I considered to be the best
balance between simplicity, execution speed and number of files.
One measured decision was to make the initialization of modules depend
only on the `':zim' modules` style, keeping it as fast as possible.
The `':zim:module' module` style is used to install, update and clean
the modules, all operations that happen after the user got his
as-blazing-fast-possible shell prompt.
Even though I didn't care much about making install or update fast,
`xargs` has a nice feature of allowing commands to be executed in
parallel with `-P`. I took advantage of that.
I've also worked on making the `zimfw` utility give the user some nice
(while still minimalistic) output. Also I'm suggesting this as the new
name for the `zmanage` tool, since `zimfw` does not shadow the `zim`
wiki tool.
2019-01-07 18:25:34 -05:00
|
|
|
|
2020-01-15 12:35:30 -05:00
|
|
|
Want to update your modules to their latest revisions? Run `zimfw update`.
|
2019-12-07 21:17:40 -05:00
|
|
|
|
2020-01-15 12:35:30 -05:00
|
|
|
Want to upgrade `zimfw` to its latest version? Run `zimfw upgrade`.
|
2019-12-07 21:17:40 -05:00
|
|
|
|
2020-01-15 12:35:30 -05:00
|
|
|
For more information about the `zimfw` tool, run `zimfw help`.
|
Add a plugin mechanism \o/
This is a major change, where Zsh modules/plugins are not git submodules
in the Zim repo anymore, but customized and installed separately as
individual repositories. The discussion about this started more than 2
years ago in #88. Closes #299.
This will allow contributors' modules to live in their own repositories.
See #33, #138, #262, #281, #324.
The current code has what, up to this point, I considered to be the best
balance between simplicity, execution speed and number of files.
One measured decision was to make the initialization of modules depend
only on the `':zim' modules` style, keeping it as fast as possible.
The `':zim:module' module` style is used to install, update and clean
the modules, all operations that happen after the user got his
as-blazing-fast-possible shell prompt.
Even though I didn't care much about making install or update fast,
`xargs` has a nice feature of allowing commands to be executed in
parallel with `-P`. I took advantage of that.
I've also worked on making the `zimfw` utility give the user some nice
(while still minimalistic) output. Also I'm suggesting this as the new
name for the `zmanage` tool, since `zimfw` does not shadow the `zim`
wiki tool.
2019-01-07 18:25:34 -05:00
|
|
|
|
2020-01-15 12:35:30 -05:00
|
|
|
Settings
|
|
|
|
|
--------
|
Add a plugin mechanism \o/
This is a major change, where Zsh modules/plugins are not git submodules
in the Zim repo anymore, but customized and installed separately as
individual repositories. The discussion about this started more than 2
years ago in #88. Closes #299.
This will allow contributors' modules to live in their own repositories.
See #33, #138, #262, #281, #324.
The current code has what, up to this point, I considered to be the best
balance between simplicity, execution speed and number of files.
One measured decision was to make the initialization of modules depend
only on the `':zim' modules` style, keeping it as fast as possible.
The `':zim:module' module` style is used to install, update and clean
the modules, all operations that happen after the user got his
as-blazing-fast-possible shell prompt.
Even though I didn't care much about making install or update fast,
`xargs` has a nice feature of allowing commands to be executed in
parallel with `-P`. I took advantage of that.
I've also worked on making the `zimfw` utility give the user some nice
(while still minimalistic) output. Also I'm suggesting this as the new
name for the `zmanage` tool, since `zimfw` does not shadow the `zim`
wiki tool.
2019-01-07 18:25:34 -05:00
|
|
|
|
2021-08-10 11:38:01 -04:00
|
|
|
Modules are installed using `git` by default. If you don't have `git`
|
|
|
|
|
installed, or if you want to take advantage of our degit tool for faster and
|
|
|
|
|
lighter module installations, you can set degit as the default tool with:
|
|
|
|
|
|
|
|
|
|
zstyle ':zim:zmodule' use 'degit'
|
|
|
|
|
|
2020-05-26 09:02:25 -04:00
|
|
|
By default, `zimfw` will check if it has a new version available every 30 days.
|
2020-01-15 12:35:30 -05:00
|
|
|
This can be disabled with:
|
Add a plugin mechanism \o/
This is a major change, where Zsh modules/plugins are not git submodules
in the Zim repo anymore, but customized and installed separately as
individual repositories. The discussion about this started more than 2
years ago in #88. Closes #299.
This will allow contributors' modules to live in their own repositories.
See #33, #138, #262, #281, #324.
The current code has what, up to this point, I considered to be the best
balance between simplicity, execution speed and number of files.
One measured decision was to make the initialization of modules depend
only on the `':zim' modules` style, keeping it as fast as possible.
The `':zim:module' module` style is used to install, update and clean
the modules, all operations that happen after the user got his
as-blazing-fast-possible shell prompt.
Even though I didn't care much about making install or update fast,
`xargs` has a nice feature of allowing commands to be executed in
parallel with `-P`. I took advantage of that.
I've also worked on making the `zimfw` utility give the user some nice
(while still minimalistic) output. Also I'm suggesting this as the new
name for the `zmanage` tool, since `zimfw` does not shadow the `zim`
wiki tool.
2019-01-07 18:25:34 -05:00
|
|
|
|
2020-01-15 12:35:30 -05:00
|
|
|
zstyle ':zim' disable-version-check yes
|
Add a plugin mechanism \o/
This is a major change, where Zsh modules/plugins are not git submodules
in the Zim repo anymore, but customized and installed separately as
individual repositories. The discussion about this started more than 2
years ago in #88. Closes #299.
This will allow contributors' modules to live in their own repositories.
See #33, #138, #262, #281, #324.
The current code has what, up to this point, I considered to be the best
balance between simplicity, execution speed and number of files.
One measured decision was to make the initialization of modules depend
only on the `':zim' modules` style, keeping it as fast as possible.
The `':zim:module' module` style is used to install, update and clean
the modules, all operations that happen after the user got his
as-blazing-fast-possible shell prompt.
Even though I didn't care much about making install or update fast,
`xargs` has a nice feature of allowing commands to be executed in
parallel with `-P`. I took advantage of that.
I've also worked on making the `zimfw` utility give the user some nice
(while still minimalistic) output. Also I'm suggesting this as the new
name for the `zmanage` tool, since `zimfw` does not shadow the `zim`
wiki tool.
2019-01-07 18:25:34 -05:00
|
|
|
|
|
|
|
|
Uninstalling
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
The best way to remove Zim is to manually delete `~/.zim`, `~/.zimrc`, and
|
2019-12-14 22:41:19 -05:00
|
|
|
remove the initialization lines from your `~/.zshenv`, `~/.zshrc` and `~/.zlogin`.
|
2016-09-05 18:36:44 -04:00
|
|
|
|
2019-01-22 19:40:43 -05:00
|
|
|
[blazing speed]: https://github.com/zimfw/zimfw/wiki/Speed
|
2021-07-01 18:58:49 -04:00
|
|
|
[modules]: https://zimfw.sh/docs/modules/
|
|
|
|
|
[themes]: https://zimfw.sh/docs/themes/
|
