[BREAKING CHANGE] [Feature] Core

[gtrabanco]

Description

This adds a lot of libs for more incoming features when this PR will be approved. These libs were added here here because were recurrently used in the other features. This also change the way dotly is loaded because some times the features need a change in bashrc or zshrc, so now bash and zsh have a loader for dotly.

Core Libraries

Core libraries modified

git.sh

• git::get_local_HEAD_hash get local HEAD of the given branch or current HEAD.
• git::get_remote_branch_HEAD_hash the commit hash of the remote branch HEAD.
• git::local_current_branch_commit_exists_remote return boolean if the given git remote branch HEAD is the same as the local branch HEAD.
• git::remote_branch_by_hash give you the remote branch name by the commit hash.
• git::current_branch modified to show the current branch.
• git::current_commit_hash get the current commit hash.
• git::get_commit_tag get tag if given commit is tagged in the local repository.
• git::get_all_local_tags
• git::get_current_latest_tag get local last tag (ordered by name).
• git::get_all_remote_tags
• git::get_all_remote_tags_version_only get remote tags but peform a format to branch name.
• git::check_local_tag_exists check if given tag exists in local repository.
• git::check_remote_tag_exists check if given tag exists in a git remote.
• git::get_submodule_property get .gitmodules property for given module.

• git::check_local_repo_is_updated check if local repository is behind remote origin repository by using git status
• git::simple_check_local_repo_is_updated the same as previous in more simple way
• git::dotly_repository_exec function to execute any function inside the DOTLY_PATH. Useful to perform git checkout or any git command that require to be executed in the git repository.
• git::check_file_exists_in_previous_commit return true if file was added in latest commit
• git::check_file_is_modified_after_commit check if a file was modified or added after the given commit
• git::get_commit_timestamp get the commit timestamp
• git::get_file_last_commit_timestamp get the timestamp of last modified or added file if exists in any commit

output.sh

• Fixed output::question get the input in a new line on macOS
• Added output::question_default which provides a default value if user no input a value in prompt.
• Added output::yesno provides a Yes/No question. It has fixed de double negation.

platform.sh

• Added platform::semver_is_minor_patch_update which compares if has a minor or patch change in semver versioning. This was added for dotly autoupdate feature.
• Added platform::semver_compare to compare semver versioning.

dot.sh

• Added dot::get_script_path to get current script path in dotly scripts. Scripts can be installed in other context in a incoming feature so would be great use this when you need a external library for a script that it is in $DOTFILES_PATH/scripts folder. This not thinked for scripts that are in DOTLY_PATH because they must be "inmutable".
• Added dot::get_full_script_path with provides full path for calling this function script.
• Added dot::get_script_src_path to load src internal script libraries (libraries in the same context as your dotly script). See dot self version.

Libraries added

templating.sh

With this library you can create files or strings that have variables inside in the way of XXX_VARIABLE_NAME_XXX, you can pipe string or pass it as argument or file (at the end) by using:

templating::replace "XXX_NAME_XXX <XXX_EMAIL_ADDRESS_XXX>" --name=Gabriel --email-address=no-email@example.com
templating::replace "XXX_NAME_XXX <XXX_EMAIL_ADDRESS_XXX>" --name Gabriel --email-address no-email@example.com
templating::replace "XXX_NAME_XXX <XXX_EMAIL_ADDRESS_XXX>" name Gabriel email-address no-email@example.com
echo "XXX_NAME_XXX <XXX_EMAIL_ADDRESS_XXX>" |\
   templating::replace name Gabriel email-address no-email@example.com
templating::replace /path/to/file --name=Gabriel --email-address=no-email@example.com
templating::replace /path/to/file --name Gabriel --email-address no-email@example.com
templating::replace /path/to/file name Gabriel email-address no-email@example.com

You can also modify a bash variable in a file using:

templating::modify_bash_file_variable "$DOTFILES_PATH/shell/exports.sh" "DOTFILES_PATH" "~/.new-dotfiles"

async.sh

Provides async functionality as the same way of promises. This is a modified version of the async function of this library:

• https://github.com/zombieleet/async-bash

I did not add the source to the README.md I don't make that decision.

array.sh

I use this with the script dot self init to get the non disabled scripts or enabled or both. With this you can get the union, difference or disjunction of array values.

files.sh

Functions:

• files::check_if_path_is_older that say true if a file or folder is older than the given time. True if is older, false if it is newer.
• files::backup_if_file_exists perform a backup of the given value and prints the path to the backup file.

Modifications to _main.sh

I consider array.sh, files.sh and async.sh core libraries. The other libraries must be added manually if you want to use them in your scripts.

Scripts modified

dot self update

Modified to keep the same branch when updating dotly because was necessary for testing autoupdate and without this autoupdate does not have sense.

dot symlinks apply

This modification it is not very important. Just added --version for the script. It was no moved to the DOCBLOC because makes no sense for me put it there and parse it when someone type --version calling the script.

dot dotfiles create

Modified to use the new core templating.sh library.

Scripts added

dot self init (THIS WAS CHANGED VIEW LAST MESSAGE IN THIS PR)

With this new script you can enable or disable script when open a new terminal or session. With this you will be able to enable or disable autoupdate.

dot self autoupdate

Executes async autoupdate. This is done here to avoid include all scripts when start the terminal which would make available all core functions that should be only available in the scripts.

dot self migration

Executes script migrations. These scripts should have the version number as name and must be executable. The idea is to make simpler the dotly update when there are breaking changes or files/directory that are new in dotfiles_template directory.

dot symlinks update

This was added to execute update scripts when you update dotly and need to make changes to your current DOTFILES_PATH.

This update yaml files in a docbot format have to be in $DOTLY_PATH/symlinks. There is one added to update old DOTFILES to this version but, .bashrc and .zshrc were not added to update them, because maybe the user want to backup them and update them manually. Feel free to add any script here if you want :)

About Autoupdate

Autoupdate need branch (tags) in the repository. It will use local tags to check if there is any update if value of DOTLY_UPDATE_VERSION takes stable or minor. It will look for update in a HEAD ref of remote repository and local repository. This is done this way because DOTLY is always updated in master and master is the production branch.

Modes (DOTLY_AUTO_UPDATE_MODE)

Autoupdate modes are:

• silent, autoupdate with no warning about a update.
• auto, update silently and just show you a message when DOTLY was updated to restart your terminal.
• info, show you a message that there is available a new DOTLY version and also add a inbox at the very beginning of your DOTLY Theme prompt.
• prompt, just show the prompt inbox in DOTLY theme if there is any update.

Version (DOTLY_UPDATE_VERSION)

• latest update to latest commit in master branch.
• stable update to latest tagged commit, because it is considered a stable commit.
• minor no update to major versions, considering that DOTLY will use a semver versioning.

IMPORTANT The semver comparison function I put in the libraries is not compatible with tags like beta, rc, alpha. Only consider number.

Variables

• DOTLY_AUTO_UPDATE_MODE by default takes auto
• DOTLY_AUTO_UPDATE_VERSION by default takes stable
• DOTLY_UPDATE_PERIOD_IN_DAYS the number of days that DOTLY should be older before start checking if there is any update.

Enable/disable autoupdater

To enable autoupdater:

dot self init enable autoupdate

To disable autoupdater:

dot self init disable autoupdate

DEVELOPERS I strong recommend disable the option if your are developing something for dotly.

Autoupdater files

Autoupdater advise the user by creating empty files in DOTFILES_PATH these files are .dotly_force_current_version, .dotly_update_available, .dotly_update_available_is_major and .dotly_updated.

These files are recommend to add them in .gitignore.

File .dotly_force_current_version is a special file that forces dotly to no update automatically, this is useful if you are developing something for dotly core.

New variables

• GITHUB_TOKEN is not necessary but recommend to get a Github token and add it to your dotfiles, if it is not present you can have errors about number of GitHub API limit reach which won't give any result to any API Call. If this is not defined you will see a message if you enable DOTLY Autoupdater or use any script that makes usage of this library.
• GITHUB_CACHE_PETITIONS_PERIOD_IN_DAYS, the number in days to keep the GitHub Cache of all API Calls. This makes this library faster.
• DOTLY_NO_INIT_SCRIPTS disable dot self init usage and initial preload of scripts. (THIS WAS CHANGED, SEE LAST MESSAGE; CURRENT NAME OF THIS VARIABLE IS ANOTHER ONE).

Fixes

• Autocompletions error while entering bash mode #93 Bash autocompletions (This was changed from the fix, now it is using find instead of ls)
• When execution dot self update automatically was switching to master branch even if you have installed from another branch. This was a rejected fix but was necessary for testing autoupdate.

Documentation

No documentation was added.

Test

Testing by usage. You can tested from my fork, this branch was applied to master if you want to test.

Other

Feel free to modify this scripts, accept or reject them but I won't work anymore on this branch because I want it as it is in my own fork. Sorry.
Anyway if you have any doubt you can ask.

Task

• Autoupdate without VERSION file.
• Update the documentation in this post about autoupdate.
• Added documentation about git.sh in this post.
• Add new files.sh function to perform backup if file exists.
• Add documentation about dot self migration script in this post.
• Update dot self update
• Adds dot self version to select a DOTLY specific version and no update it.
• Adds dot self migration to execute migration scripts after any dotly update.
• Automate apply dot self migration after update.
• Add migration script to update this dotly version.

[gtrabanco]

dot init

This is the context for previous script dot self init in this branch.

dot init enable

To enable init scripts, you can provide a script name (the file name) and if it is exists and it is disable it will enable to load on shell start. If not you will see a list of disabled scripts (just disabled, if you do not see any script is because it is already enabled), you can select multiple scripts to enable by pressin shitf+tab (fzf --multi param).

dot init disable

The same as dot init enable but to disable.

dot init status

View the status of all scripts.

Disable init scripts

If you want to disable init script just define in your exports a var:

export DOTLY_INIT_SCRIPTS=false