Rename `run` function to `main_run`

[meleu]

Description

I'd like to suggest renaming the default run function to something like main_run.

Reasoning: prevent name collision with BATS run function.

I already have a solution for this: I always put this in my bashly-settings.yml:

function_names:
  # NOTE: this is needed to prevent name collisions with BATS-core
  run: main_run

It's not a big thing for me, who already realized how to solve it. But it's another thing that adds more friction to let people (or AI agents) start testing right away.

---

UPDATE

Turns out that sourcing the whole final script is a bad practice and should be avoided. Therefore the motivation to open this thread is not valid anymore.

Since we're using Bashly, a better practice is to source only the file containing the function under test (or even all files under src/lib/ if the test requires dependencies from multiple files). Although I didn't incorporate this practice in my existing programs, I should start doing so (and encourage my colleagues accordingly).

That being said, my opinion is that keeping the entrypoint function named as run(), therefore doing nothing, is the best approach.

[DannyBen]

Well - maybe lets ask BATS to change their run function... 😜

So as it turns out, this reply has two sections:

Table of Contents:

• I Disagree
• I Agree

---

The run command is currently guaranteed as a developer-interface function, to allow rerunning functions internally by passing ARGV.

I know it is a rather weak argument, and there are probably no more than a handful of users using it - but still, changing something that feels natural, so that it wont conflict with a testing framework is arguably just as weak.

And by the way - I think you should avoid sourcing the entire bashly-generated script for your bats tests.
Since in bashly you already have different functions in different files, you can just source them.

I have used this approach in all my bats tests. Example:

• https://github.com/DannyBen/ssi/tree/master/test
• https://github.com/DannyBen/alf/tree/master/test
• https://github.com/DannyBen/shellkin/tree/master/test

Furthermore - I had a case where I needed to have a run() function that is NOT the bashly one, so I also used the settings to do so, and still, I was able to test with bats by using this trick:

eval "$(declare -f run | sed '1s/^run /bats_run /')"

which redeclares the bats run function as bats_run

Can be seen in play here

---

That said - I agree that run is a function with many potential conflicts.

Maybe a less conflicty name for it would be main()? and it would still serve the contract for developers, as they can run things like main mycli --with args and it will feel somewhat as natural.

How about this?
If we do want this - should we consider this a breaking change?

[meleu]

Maybe a less conflicty name for it would be main()?

I don't think this is a good idea, because bash, by default, name the "top level context" as main. You can see an evidence in the stacktrace example:

./download: line 15: no_such_command: command not found
./download:15 in `root_command`: no_such_command

Stack trace:
	from ./download:15 in `root_command`
	from ./download:259 in `run`  # 👈 if we call this `main`, we have duplication
	from ./download:267 in `main` # 👈 `main` is the name of the "very-first caller"

---

I think you should avoid sourcing the entire bashly-generated script for your bats tests.

You're right, it's an overkill to source the whole final script to test a single function. Maybe I just got used to do this in my pre-Bashly days.

Now I feel like this "feature request" issue should be moved to discussions while I reflect about my current bash testing practices... 🤔

[DannyBen]

Good to know about main's secret identity.

I don't mind continuing the discussion here, it will either quickly mature to a feature, or die out.

In general - I don't mind renaming, only it needs to be a good, natural name, and we will need to consider if it is a breaking one or not.

[DannyBen]

@meleu you always make me think, I like that.

It occurred to me that perhaps both of us are doing the bats sourcing wrong:

• You source the entire script (artifact) - so you end up with a lot of junk and run() collision
• I source only the function-under-test and its dependency chain - so I end up with many sources and "unsource" cleanups

What if we just add a "load all src/lib/*" in the test helper? Something along these lines:

# test_helper.bash
load_lib_tree() {
  local file
  while IFS= read -r -d '' file; do
    source "$file"
  done < <(find "${BATS_TEST_DIRNAME%/}/../src/lib" -type f -name '*.sh' -print0 | sort -z)
}

Note that this will work only for lib files, which are encapsulated as functions, and not for the "command" files.
For the command files, this is a whole new ballgame, which - I think - does not belong in a unit test framework, but rather in some integration / acceptance testing, that can either be done with bats (by actually running the CLI) or using another acceptance-friendly framework.

[pcrockett]

late to the discussion, and i only skimmed it. brief thoughts:

• i didn't know about bash's main() there. interesting.
• could call it bashly_main(). though honestly even with the top-level bash context thing, i'd still be ok with calling it main(). i use this pattern in lots of my (non-bashly) scripts personally and think it's ok.
• if we did this, i'd call it a breaking change. still not opposed to it though.
• i also wouldn't be opposed to leaving it as-is, using the setting for those who care about it. i've never encountered a conflict with bats because i don't source my scripts (i rely more on end-to-end much more than unit testing).

[DannyBen]

Yeah - I feel the same way, with one exception: no bashly_* anything in the generated scripts. The scripts do not belong to bashly, but to the user. I don't want a constant reminder that this was generated by bashly. Personally, I only had to override the default run in one occasion: When I had to create a run() function of my own that had to be named like this. The bats argument is easily avoidable, and is even preferable, by never sourcing the full generated script.

I also think the only viable names now are run() or main().
I will add this as a possibility in #657 .

[meleu]

i'd still be ok with calling it main(). i use this pattern in lots of my (non-bashly) scripts personally and think it's ok.

I was also used to use main for quick scripts. But since I started to use our stacktrace technique, with that main being mentioned, I changed my practice, naming the "entrypoint function" as the same name of the file.

I don't like main being mentioned twice because it consumes mental energy (or LLM tokens) to remember "oh! this is my main, and this is bash's main".

I prefer having the extra step of manually setting up a custom name to prevent collision (my current solution) than having dubious information in the stacktrace.

---

Proposing/brainstorming another alternative:

what do you think about renaming to run_${app_name}.

example:

# src/bashly.yml
name: my_cli
# ...

Would have the "entrypoint function" named as run_my_cli

[DannyBen]

naming the "entrypoint function" as the same name of the file.

This is actually an intriguing idea.... what's wrong with that? I mean without any prefixes.

It will then make internal calls like "mycli build" work exactly as they would as if they were called from the outside, only with internal calls.....

[meleu]

That would work nice too! 👍

[pcrockett]

🤔

i kinda like that too.

only caveat: you'd have to make certain the script file doesn't collide with any existing function names.

so for example, this would be a footgun if someone created a script called parse_requirements or initialize.

using run_ as a prefix would probably mitigate that.

[DannyBen]

As much as I enjoy entertaining the idea, I currently feel that run() is the most defensible. There is no better name yet that is clearly superior.

Evaluation Criteria

Criterion	Description	Why It Matters
Collision Risk	Likelihood of clashing with user-defined functions or common tools (e.g., Bats)	Avoid surprising breakages or forcing users to rename things
Intuitiveness	How immediately understandable the name is as the CLI entrypoint	Reduces learning curve and improves readability
Self-Dispatch Readability	How natural it feels when used to internally invoke the CLI (X foo bar)	Important because this function is part of the developer-facing API (see internal-run example)
Stability in Docs	Whether the name can be used consistently across all generated CLIs	Affects documentation clarity and example portability
Non-Framework Feel	Avoids exposing framework-specific naming (bashly_*)	Keeps generated scripts feeling clean and user-owned
“Better than run” Bar	Whether the option is a clear improvement over the current run()	Renaming has a cost; alternatives must justify it

Analysis

Option	Collision Risk	Intuitiveness	Self-Dispatch Readability	Docs Stability	Notes	Overall
run() (current)	Medium (notably Bats)	High	Excellent (run foo)	High	Already configurable via function_names.run; widely understood	Baseline
main()	Medium	High	Good (main foo)	High	Conflicts with Bash’s own main in stack traces; less expressive for dispatch	Worse than run
dispatch()	Low	Medium	Good (dispatch foo)	High	More precise but more “framework-y” / implementation-oriented	Slightly weaker
invoke()	Low–Medium	Medium	Good (invoke foo)	High	Reasonable alternative, but less natural than run	Not clearly better
<cli_name>()	Low	Medium (magical)	Excellent (mycli foo)	Low	Elegant but introduces “magic” and ambiguity when sourced	Strong but risky
<cli_name>_run etc.	Low	Low	OK	Low	Adds verbosity without meaningful benefit	Weak option
bashly_* (e.g. bashly_run)	Very Low	Low	OK	High	Explicit but too framework-exposed	Rejected by design

[meleu]

Option	Collision Risk	Intuitiveness	Self-Dispatch Readability	Docs Stability	Notes	Overall
<cli_name>_run etc.	Low	Low	OK	Low	Adds verbosity without meaningful benefit	Weak option

The judgement here was unfair. 🙁

Maybe because it saw <cli_name>_run rather than run_<cli_name>... Regardless, let me try to bring more arguments.

I don't think run_<cli_name> has low intuitiveness. That judgement is undeserved.

I also think that a collision with an always very commonly used BATS function should be taken into a higher consideration than a "trivial" collision.

My bias to defend this opinion is:

• I love bashly
• I love BATS (and testing in general)
• I love to encourage/evangelize people to use both
• I'd like them to have less friction to start using both

It's rare to see bash coders writing tests for their scripts out there. Every place I worked it's always me bringing this practice to the Bash codebase (and recently I also started to bring Bashly).

I think that the less friction between Bashly and BATS, the better. I truly believe the world (or at least my job) will be better if more bash coders use Bashly and BATS together. 🙂

[DannyBen]

I also think that a collision with an always very commonly used BATS function should be taken into a higher consideration than a "trivial" collision.

This collision does not exist, unless you are doing it wrong. You should not source your entire script, I thought we agreed it is a bad pattern.

Most of your script is not something that you need to test. If you start sourcing what is needed only - which are the lib functions - your collisions will disappear.

The pattern I recommend is:

• Source lib functions for unit tests.
• Test command themselves by executing (not sourcing) the script (with bats or other acceptance framework).

So the argument for fixing something when it is done in the suboptimal path, does not get points in my view. At least not many.

A stronger argument against run - which happens to include the bats use case - is that run is a common name, that someone, somewhere might want to use for something else. Bats contributes a small portion to this argument, but other than this argument - run is superior to all other options in my opinion still.

And as you mentioned - it is a "judgment" - so I understand that different "judges" may have different views, but I stand behind mine: Any change needs to prove it is better. run_<something_that_changes_with_every_script> is not better than run in this regard. Not even close. And if it is, why not initialize_<yourcli>? and what about other functions that may or may not collide with bats? or with other test frameworks? where does it end? All this because someone sourced something they shouldn't have? No. Not buying it yet... :)