Document how to most easily make vendor/bin/drush available as drush

drush-launcher was doing this but it is now abandoned.

Yeah, currently I've been running sudo ln -s /var/www/SITE/vendor/bin/drush /usr/local/bin/drush

Should this be handled in Drush and/or Drush documentation?

Good question @DamienMcKenna ... It is documented how to use $PATH, on the Drush install page, under "2. Execution".

My aim is to make the command drush work out of the box, right after installing Drush. Adding it to $PATH or using a symlink are both options, but ideally setting this up should be done as part of the Drush installation (if possible) or by making Drupal core link or add an alias (again, if possible).

I had a look at the WP CLI tool, and it is also moved into the $PATH ... so maybe it's just a necessary step?

I created a Drush issue and added it in the Issue summary.

As much as I like the idea, but I don't know if it's going to happen. I recall asking for this in Drush a while ago, and it was rejected because the system might have a global installation of Drush, or have multiple sites each with their own Drush dependency. Here's an illustration that shows some complexity:

If I have /var/www/site1, /var/www/site2, /var/www/site3, then adding a symlink doesn't work, because you can't have each site symlinked to /usr/local/bin/drush at the same time with different versions. You have to use the Drush that's included for the site in the current working directory somehow. We could add the symlink as /var/www/site1/drush, but then it won't work in child directories. And if you add it to the $PATH automatically, then once again you run into an issue when trying to use Drush for a specific site. If I run drush in /var/www/site1, how does it know which drush to use (site1, site2, or site3)?

Drush would essentially need to check the current working directory and look for a vendor folder, which is basically just replicating what drush-launcher did, I think.

drush's composer.json file includes this definition:

  "bin": [
    "drush"
  ],

I can then see vendor/bin/drush exists.

I suspect the issue title and summary might need to be clarified as it's not about copying the "drush" command from vendor/drush/drush/drush to vendor/bin/drush, it's about making the vendor/bin/drush command available within the system $PATH definition. This is going to be OS specific and shell specific, e.g. what works for Bash won't work for zsh, Fish Shell, csh, etc.

Personally I run Drush from within ddev, e.g.: ddev drush [command]

I prefer to have two terminals open, one for DDEV, and one inside the Docker container for running Drush commands. Having Drush in the PATH also helps with running Drush commands on a non-development server.

As a note, ddev . [command] is the same as ddev drush [command]

Yes, DDEV adds Drush to the $PATH. But if it didn't do that, you'd have to run vendor/bin/drush there as well, I suppose.

My aim is to allow drush to work out of the box in maybe 80-85% of Unix environments, so perhaps support for Bash and Zsh would cover that, as a start? This would then also work for Debian servers, and other servers running Bash.

Ps. I use an alias drush='ddev drush' (see DDEV, Drush, and Composer aliases → ).

A point of clarification: "ddev . [command]" is not the same as "ddev drush [command]". Instead, "ddev ." is an alias of "ddev exec", so you can run "ddev . drush [command]" instead of writing "ddev exec drush [command]". Furthermore they added a new default ddev command/script recently so you can shorten that to just "ddev drush [command]".

I still think it's out of scope for Drupal to worry about how people access Drush given it isn't a built in part of Drupal. It might be worth continuing to work with the Drush team to improve their documentation on helping people install it when they aren't very terminal savvy.

I am not sure I understand how that would work. I don't see how Drupal install could be able to modify your PATH or add something to /usr/local/bin/. (I definitely do not want my Drupal install to start trying to modify files outside its folder).

I think the best Drupal can do here is have some documentation on how to add Drush to your PATH.

Yes, it may be too much to ask for ... The previous solution Drush Launcher and WP Cli also involve manually moving files around, or adding to $PATH. So for now, better documentation is probably the way forward.

These are the three solutions I have found so far. I think the alias solution is the easiest, since it only requires adding a line in .bashrc and sourcing it, where adding to $PATH can get more complicated. What do you think? And then there's also @chx's solution, he shared in Archive this project? #105 (Drush Launcher), but which requires Git:

Alias

Use an alias (remove with unalias drush)

alias drush='vendor/bin/drush'

Using $PATH

Add Drush to $PATH (reset with source /etc/profile)

PATH=./vendor/bin:$PATH

Function with Git

Use Git with a function (remove with unset -f drush)

function drush () {
  $(git rev-parse --show-toplevel)/vendor/bin/drush "$@"
}

alias drush='vendor/bin/drush'

This won't work if using Drush from within a subfolder of the project. It'd be better to use the absolute path or make it relative to the project root somehow.

Also, you shouldn't add relative directories to $PATH. That's a bad idea.

Thanks for the feedback, but I always run Drush from the project root, so that's ok. Also, how would you use absolute paths, if you have more than one project? With this alias, you can switch between projects, and it works on all of them, run from the project root.

About using ./vendor/bin: This is actually the recommendation on the Drush installation page ... But if it's a bad idea, this should be updated.

Well, at the very least add it to the end of the PATH rather than the beginning. But it basically means that you're adding a lot more potential folders to the PATH, since for any command you run in a different directory on the filesystem, it will check if there's a ./vendor/bin folder and run it from there if it finds it.

I also think this is a Drush project idea, not Drupal Core's.

Thanks @solideogloria, I have updated the order in the issue summary. And yes, the original idea of fixing this in Drupal core has morphed.

Adding tip in the issue summary about using the absolute path, to allow calling Drush from any folder, if there's only one Drupal installation on the system.

Alias vs. $PATH

From the perspective of a server with multiple Drupal installations, what are the downsides to using an alias, as opposed to adding to $PATH? They share the same requirement, that they are to be used from the project root. As I see it, adding an alias is easier to deal with, and more immediately understandable.

But maybe there are good reasons to use $PATH instead?

@greg-1-anderson kindly clarified in the Github Drush issue why using alias is probably not a great idea, and I have updated the issue summary.

As always, my opinion is that we should link to the source - Drush installation instruction, not provide our own instructions. If we think the instructions are unclear, we should fix it upstream (as ressa is doing - great). Repeating the instructions here is just causing extra maintenance and confusion when, not if, the instructions are outdated / for the wrong current version.

And when we provide drush commands, we should just write

drush whatever

.

I agree @hansfn, documentation should be consolidated in one place, closest to the source.

This issue is not to be used as a documentation resource, but for finding solutions, to eventually be added to the drush.org documentation, which I have clarified in the issue summary.

I see the task list at the bottom of the issue summary now, but IMO it's not very clear that the issue is about improving the documentation on drush.org. I suggest closing this issue and only discussing on Github. It's the Drush maintainers we need to convince.

In other words: I don't see the benefit of discussing it in two locations. However, I'm sure you will keep the Github issue updated if something useful is posted here.

Well, it's a process. This issue started out as a Drupal core idea, and when that turned out to be not feasible, it got moved to another place, where it's at now. At the same time the focus changed, to be about documenting. I have moved the two remaining tasks to "Proposed resolution" at the top to make it clearer. But sure, let's close this issue and focus on the Drush issue on Github.

Automatically closed - issue fixed for 2 weeks with no activity.