commands.md

git-elegant

An assistant who carefully automates routine work with Git.

usage: git elegant [-h | --help | help | --version | version]
   or: git elegant <command> [-h | --help | help]
   or: git elegant <command> [--no-workflows] [args]
   or: git elegant [--no-workflows] <command> [args]

    -h, --help, help    displays help
    --version, version  displays program version
    --no-workflows      disables available workflows

There are commands used in various situations such as

 enable Elegnat Git services
    acquire-git          Configures your Git installation.
    acquire-repository   Configures the current local Git repository.
    clone-repository     Clones a remote repository and configures it.
    init-repository      Initializes a new repository and configures it.

 serve a repository
    prune-repository     Removes useless local branches.

 enhance contribution rules
    show-workflows       Prints file locations of the configured workflows.
    make-workflow        Makes a new workflow file.
    polish-workflow      Opens a given workflow file.

 make day-to-day contributions
    start-work           Creates a new branch.
    save-work            Commits current modifications.
    amend-work           Amends the last commit.
    show-work            Prints HEAD state.
    polish-work          Rebases HEAD interactively.
    actualize-work       Actualizes the current branch with upstream commits.

 interact with others
    deliver-work         Publishes HEAD to a remote repository.
    obtain-work          Checkouts a remote-tracking branch.

 manage contributions
    accept-work          Adds modifications to the default development branch.
    release-work         Releases the default development branch.
    show-release-notes   Prints a release log between two refs.

 and others
    show-commands        Prints Elegant Git commands.


Please visit https://elegant-git.bees-hive.org to find out more.

accept-work

usage: git elegant accept-work <branch>

Checkouts a given branch into a temporary one and rebases the head of the default development branch, checkouts the default development branch and makes a fast-forward merge of the temporary branch, and removes the temporary branch.

A <branch> can be either a local branch or a remote-tracking branch or a pattern. The pattern should be a string that is a part of the remote-tracking branch name. It is used to search the desired branch across the remotes for processing (as under the hood the pattern is passed to git elegant obtain-work, please refer to that command for the details).

If the local repository is associated with a remote one, then the remote default development branch is used instead of local one as well as it gets fetched prior to the command execution and pushed after.

If a given branch name has a full match with a local one, then the local branch is used, otherwise, the command acts with a remote one to perform checkout and deletion. As the command works with all configured remote repositories, the deletion is performed only for origin.

If there is a rebase in progress initiated by this command, it will be continued instead, otherwise, the command stops.

The command uses branch and stash pipes to preserve the current Git state prior to execution and restore after.

Approximate commands flow is

==>> git elegant accept-work task-123
git fetch --all
git checkout --force -B __eg origin/task-123
git rebase origin/master
git checkout master
git merge --ff-only __eg
git push origin master:master
git branch --delete --force __eg
git push origin --delete task-123

acquire-git

usage: git elegant acquire-git

Applies the "basics", "standards", and "aliases" configurations to the current Git installation using git config --global.

The command may ask to provide some information that is needed for Git configuration. All further executions require fewer inputs as Elegant Git reuses previous values and will require inputs in case of new configuration options are added.

To find out what will be configured, please visit https://elegant-git.bees-hive.org/en/latest/configuration/

acquire-repository

usage: git elegant acquire-repository

Applies the "basics", "standards", "aliases", and "signature" configurations to the current Git repository using git config --local. The command asks to provide information that is needed for the current repository configuration.

The behavior of the command varies depend on git elegant acquire-git execution (a global configuration). If the global configuration is applied, then this command configures repository-related staffs only, otherwise, it applies all configurations to the current local repository.

To find out what will be configured, please visit https://elegant-git.bees-hive.org/en/latest/configuration/

actualize-work

usage: git elegant actualize-work [branch-name]

Rebases the head of the upstream branch into the current one. By default, the upstream branch is the default development branch.

A [branch-name] argument allows you to redefine the upstream branch. It supports both local and remote branches.

If the upstream branch is a remote branch, a fetch is invoked before making a rebase in order to get the latest changes.

If there is a rebase in progress initiated by this command, it will be continued prior to running the main logic.

The command uses stash pipe to preserve the current Git state prior to execution and restore after.

Approximate commands flow is

==>> git elegant actualize-work origin/some-work
git fetch
git rebase origin/some-work

amend-work

usage: git elegant amend-work

Amends the last commit by incorporating the current state of the repository. The command provides full control of what modifications should be included by starting an interactive commit process.

The command doesn't allow to modify the history of the protected branches.

Approximate commands flow is

==>> git elegant amend-work
git add --interactive
git diff --cached --check
git commit --amend

clone-repository

usage: git elegant clone-repository [options] <repository> [<directory>]

Clones a repository into a new directory and runs its configuration.

The command accepts everything that git clone command accepts. Run git clone --help to see the available options.

Approximate commands flow is

==>> git elegant clone-repository --depth 5 git@github.com:bees-hive/elegant-git.git my-dir
git clone --depth 5 git@github.com:bees-hive/elegant-git.git my-dir
cd my-dir
git elegant acquire-repository

deliver-work

usage: git elegant deliver-work [branch-name]

Rebases the head of the remote default development branch into the current one and pushes the branch to the remote default upstream repository.

The command doesn't allow to push a protected branch.

A [branch-name] name is a name of a remote-tracking branch in the remote default upstream repository. By default, it is equal to the name of the current local branch. However, if HEAD has a configured remote-tracking branch, it will be used. But if the [branch-name] argument is provided, it will be used as the name of the remote-tracking branch.

If there is a rebase in progress, the command will pick it up as a part of the execution flow.

If the push output contains an URL (like a link to create a pull request), it will be open (in case if open command is available) in a default browser.

The command uses stash pipe to preserve the current Git state prior to execution and restore after.

Approximate commands flow is

==>> git elegant deliver-work
git fetch
git rebase origin/master
git push --set-upstream --force origin task-123:task-123

init-repository

usage: git elegant init-repository

Creates an empty Git repository (or reinitialize an existing one), runs its configuration, and creates an initial empty commit.

Approximate commands flow is

==>> git elegant init-repository
git init
git elegant acquire-repository
git commit --allow-empty --file a-message-of-initial-commit
git show

make-workflow

usage: git elegant make-workflow <command> <type> <location>

Makes a new workflow file for a given Elegant Git command and opens it for the further scripting in the default text editor. The created file will have a shebang line pointing to #!/usr/bin/env sh -e and executable permissions. That's why the created file becomes an executable one by default. All needed directories will be created if any.

A <command> is a name of Elegant Git command.

A <type> defines whether it should be executed ahead or after the given command.

A <location> defines the availability such as personal (located at .git/.workflows) or common (located at .workflows).

Approximate commands flow is

==>> git elegant make-workflow show-work ahead common
mkdir -p .workflows
touch .workflows/show-work-ahead
chmod +x .workflows/show-work-ahead
vim .workflows/show-work-ahead

obtain-work

usage: git elegant obtain-work <name> [local branch]

Seeks across all remote repositories for a branch matching with a given name and checkouts it.

A <name> is a full or a partial name (a pattern) of the remote-tracking branch. If the pattern is specified and there are more then 1 matching branch, the execution stops with a corresponding error message.

A [local branch] is the name of the local branch in the local repository to checkout into. By default, it responds to the name of the remote-tracking branch. However, if this argument is provided, the given name is set for the local branch.

Approximate commands flow is

==>> git elegant obtain-work 133 task-133
git fetch --all
git checkout -B task-133 custom-remote/feature/133

polish-work

usage: git elegant polish-work

Finds the new commits in HEAD (a delta in commits between the current and the default development branches) and runs interactive rebase against them.

If there is a rebase in progress, the command will pick it up and continue.

The command doesn't allow to modify the history of the protected branches.

The command uses stash pipe to preserve the current Git state prior to execution and restore after. This means that the uncommitted local modifications, if they are present, will be stashed. And they will be uncovered if the rebase completes without errors or interruptions like for solving conflicts, etc. Otherwise, please run git stash pop to get them.

Approximate commands flow is

==>> git elegant polish-work
git rebase --interactive @~5

polish-workflow

usage: git elegant polish-workflow <file path>

Opens a given workflow file in the default text editor. If given file is not present, the command raises an error.

A <file path> is a path to the desired workflow file.

Approximate commands flow is

==>> git elegant polish-workflow .workflows/show-work-ahead
vim .workflows/show-work-ahead

prune-repository

usage: git elegant prune-repository

Identifies useless branches within the current repository and removes them. A branch is useless if it either has an unavailable remote-tracking branch (1) or does not have new commits comparing to the default development branch (2).

1 - Usually, a local branch has this state when an appropriate remote-tracking branch was merged and removed. As these manipulations were made on the server side, the local branch is still present, but useless.

2 - This kind of branches appears when a branch is created for some purposes but does not have any commits nowadays. So, it is useless.

Approximate commands flow is

==>> git elegant prune-repository
git checkout master
git fetch --all
git rebase
git branch --delete --force task-24
git branch --delete --force 2349
git branch --delete --force task-1

The command works even if the remotes are unavailable.

release-work

usage: git elegant release-work [name]

Annotates the head commit of the default development branch by adding anotated tag, publishes it to the remote repository, and prepares release notes.

A [name] is a desired name for the new tag. If it isn't provided, the command will ask it interactively.

The command generates a tag's message that has to be polished and saved. The message is a list of commits titles generated based on commits between the last tagged commit (not included) and head one (included) ordered from oldest to newest. If there are no tags in the repository, then all commits are used to generate the tag's message.

The release notes are the output of git elegant show-release-notes smart ... command. They are either copied to the clipboard (if pbcopy or xclip commands are available) or printed to the standard output.

The command uses branch and stash pipes to preserve the current Git state prior to execution and restore after.

Approximate commands flow is

==>> git elegant release-work 1.2.0
git checkout master
git pull --tags
git tag --annotate --file tag-message --edit 1.2.0
git push --tags
git elegant show-release-notes smart 1.1.12 1.2.0

save-work

usage: git elegant save-work

Saves available modifications as a new commit. The command provides full control of what modifications should be included by starting an interactive commit process.

The command doesn't allow to modify the history of the protected branches.

If there are trailing whitespaces in the modifications, the commit is rejected.

Approximate commands flow is

==>> git elegant save-work
git add --interactive
git diff --cached --check
git commit

show-commands

usage: git elegant show-commands

Prints all available Elegant Git commands to the standard output. This command is useful for completion functions as well as for other cases when you need iteration over the available commands.

Approximate command's output is

==>> git elegant show-commands
start-work
show-commands
....

show-release-notes

usage: git elegant show-release-notes [<layout>] [<from-ref>] [<to-ref>]

Prints commit titles of the commits between the given refs ordered from oldest to newest.

A layout defines a formatting for the output - simple or smart. The simple layout prints the messages as a plain text (the default one) while the smart one prints the messages in an adopted form for a Git hosting service. If the hosting service is unknown, the default layout is used.

For Github, the smart layout prints an HTML that includes HTML links to the commits and issues if possible.

A from-ref is a ref to start work from (not included to the output). By default, it is the last tag. If there are no tags, the command uses the first commit in HEAD.

A to-ref is a ref to stop work with (included to the output). By default, it is a HEAD.

Approximate command's output is

==>> git elegant show-release-notes
Release notes
- Add `show-release-notes` command
- Add `release-work` command

show-work

usage: git elegant show-work

Prints HEAD state by displaying local and remote-tracking (if available) refs, commits that aren't in the default development branch, uncommitted modifications, and available stashes.

Approximate commands flow is

==>> git elegant show-work
git log --oneline master..@
git status --short
git stash list

show-workflows

usage: git elegant show-workflows

Prints all personal and common workflows files that are available in the repository.

There are two types of workflows. The personal workflows are located in .git/.workflows directory while the common ones are in '.workflows`. All directories are located relatively to the repository root directory.

Approximate command's output is

==>> git elegant show-workflows
.git/.workflows/accept-work-after
.workflows/amend-work-ahead
.workflows/amend-work-after
.workflows/release-work-after
.workflows/save-work-ahead
.workflows/save-work-after
....

start-work

usage: git elegant start-work <name> [from-ref]

Creates a new local branch based on the head of the default development branch.

A <name> is the name of the new branch.

A [from-ref] overrides the default development branch with a given one.

If there is a remote repository, the default development branch is updated prior to creating a new one. However, if the remote repository is unavailable, the local branch is used.

The command uses stash pipe to preserve the current Git state prior to execution and restore after.

Approximate commands flow is

==>> git elegant start-work task-123
git stash save elegant-git
git checkout master
git pull
git checkout -b task-123
git stash apply stash^{/elegant-git}
git stash drop stash@{0}