settings.yml vs bashly.yml

[4lejandrito]

Hi!

I wonder why the settings.yml and bashly.yml need to coexist. I believe bashly.yml should be the single source of definition and configuration. Why do I think this way?:

1. If I see the final layout of my cli project:

   cli
     src
     settings.yml
   

   I have no clue that this is a bashly project. Whereas something like this:

   cli
     src
     bashly.yml
   

   is much cleaner in my opinion, where both definition and configuration live in the same bashly.yml file.
2. They live in different directories and I don't really understand why. I believe bashly.yaml is more important and yet it gets buried into the src folder.
3. The commands_dir and target_dir are not consistent. The former expects a relative url to the src folder and the latter to the parent folder.

   target_dir: bin
   commands_dir: commands
   

   If they lived both in the same bashly.yaml file in the root folder it would be more intuitive.

What do you think?

[4lejandrito]

In the projects I use bashly for I end up changing the path to the settings file for it to live near bashly, which I think is cleaner. See https://github.com/4lejandrito/cliferay/blob/master/Makefile#L6.

[DannyBen]

I get why this may be confusing, especially for people coming to bashly at this stage, after it evolved over time.

Everything you mentioned has a reason that may not be readily apparent, and was discussed multiple times in both issues and discussions. I will try to explain the rationale for the decisions you mentioned.

bashly.yml is the data structure

All properties in its root, map directly to a Command class.

Similarly, all subcommands map to the same class, and flags, arguments, environment variables etc - all map to their respective class in the Script namespace.

settings.yml defines everything else including the environment itself

Think of it as a centralized place to define environment variables. This file is expected to live in the same directory where you run bashly. One reason for it, is that it tells bashly where to look for other files and directories, so it cannot live inside any directory itself.

As a side note, I am not sure you know you can rename settings.yml to bashly-settings.yml (docs).

Having bashly.yml in ./src

The philosophy is to have everything (except what is not possible, or has a good reason not to) live in the src folder, similar to how other programming languages expect you to structure your files. Furthermore, the bashly.yml file - which as we concluded, defines the structure - lives next to the files that make this structure meaningful - it is the skeleton and the bash scripts (partials) are the flesh.

commands_dir is relative to src_dir

This is the case because commands_dir is doing two things: It tells bashly to store commands in a different structure (subfolder per command), AND it tells bashly which folder to use. Your command files are "src", so there should be no reason whatsoever to put them in a folder that is NOT under src.

It is relative in concept, and relative in definition.

About "intuition"

Bashly is a somewhat complex system. It handles many things, allowing flexibility for hopefully many use cases and developer habits. We try to keep the need for "intuition" to a minimum. This is done by providing the most complete yet succinct documentation possible - both online and in the CLI directly using bashly doc --help - and by providing "utility commands", like bashly init, bashly add settings, etc.

Working with bashly effectively and efficiently takes some reading and perhaps some getting used to, but hopefully the friction is kept to a minimum and dissipates over time.

As you have already discovered, you can modify the location of the settings file with an environment variable, and to define most of the options in the settings using environment variables. This flexibility comes to support people with varying intuitions and expectations.