*.plugin.zsh files will be automatically detected and loaded by ZSH frameworks.

Add one that adds the utilities folder to the user's $PATH.

Jun 04 '23 13:06 unixorn

Added sourcing the helper functions

Jun 05 '23 05:06 unixorn

Sorry for the delay in getting back to you on this.

I am not a zsh user so I'll need instructions on how to test this, how users are expected to use it, and what dependencies it has (i.e., does this require oh-my-zsh or something else to work?). Also, is this meant to supplant the built-in mechanism of modifying .zshrc?

Jun 21 '23 05:06 gnachman

Basically, this is a supplement to manually modifying .zshrc.

If a user is using any of the ZSH frameworks (not just oh-my-zsh), having a plugin file makes it easy to have the framework handle loading the integration. Many of the frameworks will even handle automatically running git clone to initially load the tool, and will periodically run git pull to keep the user's environment up to date.

Basically if someone's using a framework, a plugin file will make it easier to use the integration, and if they aren't, it won't harm anything.

I didn't see install instructions in the top level README or I would have added framework usage instructions there.

Jun 21 '23 20:06 unixorn

Sorry for the delay in getting back to you.

I really need detailed instructions on how to test this.

Aug 20 '23 18:08 gnachman

ZSH frameworks can load plugins that follow the ZSH plugin standard during startup - for example, if the end user uses zgenom, they'd add zgenom load gnachman/iTerm2-shell-integration to their .zshrc and zgenom would automatically clone the repo from github, and during session startup, look for a file named something.plugin.zsh (there are some other extensions in the standard too, but .plugin.zsh is what I used in the PR) and source it.

The plugin file I added adds the repo's utilities directory to the user's $PATH and sources the functions in shell_integration/zsh, it doesn't alter the integration, just makes it easier for framework users to load it automatically.

Aug 20 '23 20:08 unixorn

@unixorn the plugin.zsh file-name doesn't exactly match with the repository name and therefore could cause issues with plugin-managers. The T in the repo-name is uppercase and e.g. zimfw (plugin manager) looks for a .plugin.zsh file containing exactly that name.

Don't know if only zimfw is case-sensitive or the container env (as it's Linux) was the culprit here.

@gnachman you can run it in a container to try it out. Here's a Dockerfile that you can use:

FROM zshusers/zsh:5.9
RUN useradd -ms /usr/bin/zsh zshuser
RUN install_packages curl ca-certificates git
RUN echo 'source "$HOME"/.zshrc' >> /etc/profile.d/zsh
USER zshuser
WORKDIR /home/zshuser
ENV HOME=/home/zshuser
ENV ZDOTDIR=/home/zshuser
ENV ZIM_HOME=/home/zshuser/zimfw
RUN curl -fsSL --create-dirs -o ${ZIM_HOME}/zimfw.zsh \
  https://github.com/zimfw/zimfw/releases/latest/download/zimfw.zsh

RUN echo '[[ ! ${ZIM_HOME}/init.zsh -nt ${ZDOTDIR:-${HOME}}/.zimrc ]] \ 
  && source ${ZIM_HOME}/zimfw.zsh init -q; \
  source ${ZIM_HOME}/init.zsh' >> .zshrc
RUN echo 'zmodule unixorn/iTerm2-shell-integration --branch add-plugin-file' >> .zimrc

ENTRYPOINT [ "/usr/bin/zsh", "-l" ]

Aug 24 '23 15:08 nunico

Sorry for taking so long to get to this. I'd like to merge it but I don't understand how it's supposed to be used.

Where does this file go when installed? What steps should a user take to use it?

I'm not a zsh user so please assume I don't know anything about their plugin ecosystem.

Oct 17 '23 20:10 gnachman

Basically, most ZSH frameworks can be configured to clone a repository. If there's a file named something.plugin.zsh at the top level of the repository, the framework will source that file during startup.

The iTerm2-shell-integration.plugin.zsh file I've added adds the repo's utilities directory to the user's $PATH, and sources shell_integration/zsh so that the user can use the functions and script in their ZSH environment without having to alter their .zshrc.

The better frameworks will even periodically do a git pull on the plugin repositories they use to ensure that the user has the latest versions without having to do manual git operations.

Oct 19 '23 23:10 unixorn

Basically, adding this file makes it a lot more convenient for ZSH framework users to use the integration and to keep the version they're using current.

Oct 19 '23 23:10 unixorn

What do I do to try it out?

Oct 29 '23 17:10 gnachman

If you source the file, it should update your $PATH to include the repository's shell_integration/zsh and utilities directories.

At the end of the day, what ZSH frameworks do is make it easy to clone repositories, keep their copy up to date, and source their .plugin.zsh files during startup.

Oct 29 '23 20:10 unixorn

@unixorn I think what is needed here in the instructions is actual executable code that the user has to use to get the plugin working not just describing in English what to do.

Mar 16 '24 10:03 bestlem

Added an install section to README.md

Mar 19 '24 16:03 unixorn

Anything else I need to do to get this merged?

Aug 08 '24 14:08 unixorn

@unixorn Can you explain to me (a non-zsh user) how to test this?

Aug 08 '24 23:08 gnachman

Testing

Run a zsh shell
clone the repo (ZSH frameworks like zgenom/antigen/etc will do this automatically when the repo is added to their configuration)
source iterm2-shell-integration.plugin.zsh (ZSH frameworks will handle this automatically for the end user)
Check $PATH - it should now have repocheckout/utilities added to it

That's pretty much it. The reason to have a iterm2-shell-integration.plugin.zsh file is convenience - people using frameworks can let their frameworks handle cloning the repository, adding it to their $PATH and more importantly, keeping their local copy up to date without them having to remember to run git pull periodically.

Keeping that functionality in the .plugin.zsh file gives framework users ease of use without affecting non-zsh users.

Aug 09 '24 14:08 unixorn

Add a plugin.zsh file to be ZSH-framework friendly

Testing