diff --git a/.github/workflows/greetings.yml b/.github/workflows/greetings.yml index 1f83815..a70cfa3 100644 --- a/.github/workflows/greetings.yml +++ b/.github/workflows/greetings.yml @@ -10,7 +10,7 @@ jobs: with: repo-token: ${{ secrets.GITHUB_TOKEN }} issue-message: >- - Thank you for submitting the first issue! + Thank you for submitting the first issue! You're making a great contribution to improve Elegant Git. pr-message: >- Thank you for making the first contribution! diff --git a/.workflows/docs.py b/.workflows/docs.py index 10ae96b..e704e6d 100644 --- a/.workflows/docs.py +++ b/.workflows/docs.py @@ -19,6 +19,8 @@ def header(command: str): def normalize_command_line(line: str): if line.startswith("usage:"): return f"```bash\n{line}\n```\n" + if line.startswith("http"): + return f"<{line}>\n" return f"{line}\n" @@ -27,7 +29,7 @@ def body() -> Sequence[str]: data = [] print("Explain 'git-elegant'...") data.append(header("git-elegant")) - data.append("```bash\n") + data.append("```\n") data.extend(map(lambda line: f"{line}\n", command_output("bin/git-elegant"))) data.append("```\n\n") for command in command_output(["bin/git-elegant", "show-commands"]): diff --git a/README.md b/README.md index 94509a6..0d911ab 100644 --- a/README.md +++ b/README.md @@ -97,8 +97,8 @@ If you need to write a message to the system output, please use public functions for printing them. ### Debug mode -You can enable debug mode by running `export GED=1` (the equivalent of `set -x` for `bash`). -Run `unset GED` to switch debug off. +You can enable debug mode by running `export GED=1` (the equivalent of `set -x` for `bash`). +Run `unset GED` to switch debug off. ### Testing procedure A testing procedure consists of 3 steps: @@ -148,7 +148,7 @@ The behavior should be descriptive-style (`stops with exit code 45 if cloneable rather than imperative-style (`stop with exit code 45 if cloneable URL is not set`). ### Updating documentation -In order to get the documentation preview locally, please install required dependencies with +In order to get the documentation preview locally, please install required dependencies with `pip install -r docs/requirements.txt`. After, run `./workflows serve-docs`. That's it! The [docs/commands.md](docs/commands.md) generates by running `./workflows generate-docs` script. diff --git a/completions/_git-elegant b/completions/_git-elegant index 7230e75..b735949 100755 --- a/completions/_git-elegant +++ b/completions/_git-elegant @@ -11,24 +11,24 @@ _git-elegant (){ typeset -A opt_args _arguments -C ':command:->command' '*::option:->option' local all_commands=( - 'accept-work:applies a branch on top of \`master\` branch' - 'acquire-git:configures a Git installation' - 'acquire-repository:configures current repository' - 'amend-work:amends some changes to the most recent commit' - 'clone-repository:clones a repository and configures it' - 'deliver-work:publishes current branch to a remote repository' + 'accept-work:adds modifications to the default development branch' + 'acquire-git:configures your Git installation' + 'acquire-repository:configures the current local Git repository' + 'amend-work:amends the last commit' + 'clone-repository:clones a remote repository and configures it' + 'deliver-work:publishes HEAD to a remote repository' 'init-repository:initializes a new repository and configures it' - 'make-workflow:makes a new workflow file for the repository' - 'obtain-work:checkouts a remote branch matching by a name' - 'polish-work:reapplies branch commits interactively' - 'polish-workflow:edits a given workflows file' + 'make-workflow:makes a new workflow file' + 'obtain-work:checkouts a remote-tracking branch' + 'polish-work:rebases HEAD interactively' + 'polish-workflow:opens a given workflow file' 'prune-repository:removes useless local branches' - 'release-work:releases available work as a new annotated tag' + 'release-work:releases the default development branch' 'save-work:commits current modifications' - 'show-commands:prints available Elegant Git commands' - 'show-release-notes:prints a release log between two references' - 'show-work:shows a state of current work in progress' - 'show-workflows:shows configured workflows in the repository' + 'show-commands:prints Elegant Git commands' + 'show-release-notes:prints a release log between two refs' + 'show-work:prints HEAD state' + 'show-workflows:prints file locations of the configured workflows' 'start-work:creates a new branch' ) diff --git a/docs/commands.md b/docs/commands.md index 473f978..a754d98 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -1,5 +1,5 @@ # `git-elegant` -```bash +``` An assistant who carefully automates routine work with Git. @@ -15,37 +15,37 @@ usage: git elegant [-h | --help | help | --version | version] There are commands used in various situations such as enable Elegnat Git services - acquire-git Configures a Git installation. - acquire-repository Configures current repository. - clone-repository Clones a repository and configures it. + 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 Shows configured workflows in the repository. - make-workflow Makes a new workflow file for the repository. - polish-workflow Edits a given workflows file. + 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 some changes to the most recent commit. - show-work Shows a state of current work in progress. - polish-work Reapplies branch commits interactively. + amend-work Amends the last commit. + show-work Prints HEAD state. + polish-work Rebases HEAD interactively. interact with others - deliver-work Publishes current branch to a remote repository. - obtain-work Checkouts a remote branch matching by a name. + deliver-work Publishes HEAD to a remote repository. + obtain-work Checkouts a remote-tracking branch. manage contributions - accept-work Incorporates a branch on top of the `master`. - release-work Releases available work as a new annotated tag. - show-release-notes Prints a release log between two references. + 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 available Elegant Git commands. + show-commands Prints Elegant Git commands. Please visit https://elegant-git.bees-hive.org to find out more. @@ -58,15 +58,28 @@ Please visit https://elegant-git.bees-hive.org to find out more. usage: git elegant accept-work ``` -Checkouts a given local or remote branch into a temporary one. Then, it makes -a rebase of the latest version of the default upstream branch (`master`) with -current changes. The final rebased index merges using fast-forward strategy -into the default local branch and pushes into the default upstream branch -(`origin/master`). After a successful push, the temporary branch is removed -as well as the given branch if it locates in `origin` remote. +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 `` 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 there is a rebase in progress and it is initiated by this command, it will -be continued instead; otherwise, the command stops. +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. @@ -87,17 +100,19 @@ git push origin --delete task-123 # `acquire-git` ```bash -usage: git elegant acquire-repository +usage: git elegant acquire-git ``` Applies the "basics", "standards", and "aliases" configurations to the current Git installation using `git config --global`. -During the first execution, you will be asked to provide some information. -After, Elegant Git will automatically detect what should be changed. +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` @@ -106,10 +121,16 @@ usage: git elegant acquire-repository ``` Applies the "basics", "standards", "aliases", and "signature" configurations -to the current Git repository using `git config --local`. +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/ + # `amend-work` @@ -117,8 +138,11 @@ https://elegant-git.bees-hive.org/en/latest/configuration/ usage: git elegant amend-work ``` -Updates the most recent commit by adding some changes. The command will fail if -you'll try to modify history of the default local branch. +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 default development branch. Approximate commands flow is ```bash @@ -136,6 +160,9 @@ usage: git elegant clone-repository Clones a repository into a new directory and runs its configuration. +A `` is an Git URL to the repository to clone from (see +`git clone --help` for the details). + Approximate commands flow is ```bash ==>> git elegant clone-repository git@github.com:bees-hive/elegant-git.git @@ -150,21 +177,24 @@ git elegant acquire-repository usage: git elegant deliver-work [branch-name] ``` -Updates the current branch by rebasing the default upstream branch. If there is -a rebase in progress, the command will continue it instead of initiation a new -one. Then, it pushes HEAD to the appropriate upstream branch. +Rebases the head of the remote default development branch into the current one +and pushes the branch to the remote default upstream repository. -By default, the name of remote branch is equal to the local one. If a local -branch has an upstream branch configured, it will be used as a remote branch. -If you provide a custom name of the remote branch, it will be used as a remote -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. -The command uses stash pipe to preserve the current Git state prior to execution -and restore after. +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 ```bash ==>> git elegant deliver-work @@ -203,13 +233,14 @@ 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 `type` defines whether it should be executed `ahead` or `after` the +A `` is a name of Elegant Git command. + +A `` defines whether it should be executed `ahead` or `after` the given command. -And `location` defines the availability such as personal (located at +A `` defines the availability such as personal (located at `.git/.workflows`) or common (located at `.workflows`). - Approximate commands flow is ```bash ==>> git elegant make-workflow show-work ahead common @@ -222,19 +253,26 @@ vim .workflows/show-work-ahead # `obtain-work` ```bash -usage: git elegant obtain-work [local branch] +usage: git elegant obtain-work [local branch] ``` -Seeks across all upstreams for a branch matching by a given full or partial -name. If there are more then 1 matching branch, execution stops with a -corresponding error message. By default, the name of the local branch responds -to the remote one. However, it can be overridden by giving a second argument. +Seeks across all remote repositories for a branch matching with a given name +and checkouts it. + +A `` 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 ```bash -==>> git elegant obtain-work new-feature task-133 +==>> git elegant obtain-work 133 task-133 git fetch --all -git checkout -B task-133 custom-remote/new-feature +git checkout -B task-133 custom-remote/feature/133 ``` # `polish-work` @@ -243,19 +281,19 @@ git checkout -B task-133 custom-remote/new-feature usage: git elegant polish-work ``` -Reapplies branch commits using interactive rebase. It uses only new commits that -aren't in `master` branch. If there is a rebase in progress, the command will -continue it. +Finds the new commits in HEAD (a delta in commits between the current and the +default development branches) and runs interactive rebase against them. -Prior to the execution and in the case of rebase initiation, all uncommitted -tracked modifications will be temporally stashed. And they will be uncovered if -the rebase completes without errors, otherwise, you need to apply them manually -by running `git stash pop`. +If there is a rebase in progress, the command will pick it up and continue. -The command raises error 42 if it runs against `master` branch. +The command doesn't allow to modify the history of the default development +branch. -The command uses stash pipe to preserve the current Git state prior to execution -and restore after. +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 ```bash @@ -266,12 +304,14 @@ git rebase --interactive @~5 # `polish-workflow` ```bash -usage: git elegant polish-workflow +usage: git elegant polish-workflow ``` Opens a given workflow file in the default text editor. If given file is not present, the command raises an error. +A `` is a path to the desired workflow file. + Approximate commands flow is ```bash ==>> git elegant polish-workflow .workflows/show-work-ahead @@ -285,12 +325,12 @@ usage: git elegant prune-repository ``` Identifies useless branches within the current repository and removes them. A -branch is useless if it either has configured an unavailable upstream branch (1) -or does not have new commits comparing to `master` branch (2). +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 branch was -merged to a remote target branch and was removed. Since these manipulations were -made on server side, the local branch is still present, but useless. +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. @@ -311,15 +351,24 @@ The command works even if the remotes are unavailable. # `release-work` ```bash -usage: git elegant release-work [tag name] +usage: git elegant release-work [name] ``` -Annotates the latest commit of `master` branch with a given tag and publishes -it. The tag's message will be prepopulated using commits subjects (from oldest -to newest) between the last available tag and HEAD. If there are no tags, then -all commits will be used. The release notes will be either copied to clipboard -(if `pbcopy` or `xclip` is available) or printed to standard output using -`git elegant show-release-notes`. +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. @@ -340,9 +389,13 @@ git elegant show-release-notes smart 1.1.12 1.2.0 usage: git elegant save-work ``` -Saves available changes as a new commit. You can choose which modifications -should be added. If there are trailing whitespaces, the commit won't be -performed. +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 add a commit to the default development branch. + +If there are trailing whitespaces in the modifications, the commit is rejected. Approximate commands flow is ```bash @@ -358,9 +411,9 @@ git commit usage: git elegant show-commands ``` -Displays all available Elegant Git commands. This is useful for completion -functions as well as for other cases when you need iteration over the available -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 ```bash @@ -373,20 +426,26 @@ show-commands # `show-release-notes` ```bash -usage: git elegant show-release-notes [ | | ] +usage: git elegant show-release-notes [] [] [] ``` -Generates a release notes using commits subjects between the given references. -The commits are ordered from oldest to newest. By default, the `from-reference` -is the last available tag, and the `to-reference` is a HEAD revision. If -there are no tags, all commits will be displayed. +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. -There are two options for a `layout`: +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. -1. `simple` prints the messages as a plain text (default one) -2. `smart` prints the messages in a form of adopted for a git hosting. If the -hosting is unknown, the default layout is used. Now only GitHub is supported -(an HTML output). +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 ```bash @@ -402,9 +461,9 @@ Release notes usage: git elegant show-work ``` -Shows a state of current work by displaying branch information, new commits -comparing to `master` branch, uncommitted modifications, and available -stashes. +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 ```bash @@ -420,11 +479,12 @@ git stash list usage: git elegant show-workflows ``` -Shows all personal and common workflows files that are available in the +Prints all personal and common workflows files that are available in the repository. -Personal workflows are located in `.git/.workflows` directory and common ones -are in \'.workflows` relatively to the repository root directory. +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 ```bash @@ -444,11 +504,15 @@ Approximate command's output is usage: git elegant start-work [from-ref] ``` -Creates a new local branch based on the latest version of the default upstream -branch. If there are some uncommitted changes, they will be moved to the new -branch. +Creates a new local branch based on the head of the default development branch. + +A `` is the name of the new branch. -`from-ref` argument overrides the default upstream branch with a given one. +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. @@ -463,5 +527,3 @@ git checkout -b task-123 git stash apply stash^{/elegant-git} git stash drop stash@{0} ``` - -The command works even if a remote is unavailable. diff --git a/docs/getting-started.md b/docs/getting-started.md index ddcdf58..d1e9228 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -36,6 +36,6 @@ git-elegant where `` is one of the commands described on the [commands](commands.md) page or printed in a terminal after running `git elegant`. -Also, please use [`git elegant clone-repository`](commands.md#clone-repository) or -[`git elegant init-repository`](commands.md#init-repository) instead of regular `clone` or `init` +Also, please use [`git elegant clone-repository`](commands.md#clone-repository) or +[`git elegant init-repository`](commands.md#init-repository) instead of regular `clone` or `init` Git's commands in order to get Elegant Git working by default. diff --git a/docs/index.md b/docs/index.md index 0bcca18..b186c10 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,9 +22,9 @@ picture-in-picture" allowfullscreen> available [commands](commands.md)._ # Workflows -While developing something, it may be required to format code prior to committing changes or to open -several URLs to report release notes after a new release. All these and similar actions, which you -have to perform in addition to git actions, are your **_workflows_**. And Elegant Git allows +While developing something, it may be required to format code prior to committing modifications or +to open several URLs to report release notes after a new release. All these and similar actions, +which you're performing in addition to Git actions, are the **_workflows_**. And Elegant Git allows automating them (it's like [Git Hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks), but for Elegant Git commands). diff --git a/libexec/git-elegant b/libexec/git-elegant index e8693b0..61d43c4 100755 --- a/libexec/git-elegant +++ b/libexec/git-elegant @@ -28,9 +28,9 @@ git-verbose-op() { ${processor} "$(git "$@" 2>&1)" } -MASTER="master" -REMOTE_NAME="origin" -RMASTER="${REMOTE_NAME}/master" +DEFAULT_BRANCH="master" +DEFAULT_UPSTREAM_REPOSITORY="origin" +DEFAULT_REMOTE_TRACKING_BRANCH="${DEFAULT_UPSTREAM_REPOSITORY}/${DEFAULT_BRANCH}" _error-if-empty() { # _error-if-empty diff --git a/libexec/git-elegant-accept-work b/libexec/git-elegant-accept-work index 82ff524..fbf1804 100644 --- a/libexec/git-elegant-accept-work +++ b/libexec/git-elegant-accept-work @@ -3,7 +3,7 @@ set -e command-purpose() { cat <\` 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. @@ -64,20 +77,20 @@ MESSAGE git elegant obtain-work "${changes}" "${work_branch}" fi if are-there-remotes; then - git-verbose rebase ${RMASTER} + git-verbose rebase ${DEFAULT_REMOTE_TRACKING_BRANCH} else - git-verbose rebase ${MASTER} + git-verbose rebase ${DEFAULT_BRANCH} fi fi local actual_remote=$(git for-each-ref --format='%(upstream:short)' refs/heads/${work_branch}) - git-verbose checkout ${MASTER} + git-verbose checkout ${DEFAULT_BRANCH} git-verbose merge --ff-only ${work_branch} git-verbose branch --delete --force ${work_branch} if are-there-remotes; then - git-verbose push ${REMOTE_NAME} ${MASTER}:${MASTER} + git-verbose push ${DEFAULT_UPSTREAM_REPOSITORY} ${DEFAULT_BRANCH}:${DEFAULT_BRANCH} if [[ ${actual_remote} =~ ^origin/ ]]; then source ${BINS}/plugins/transformation - git-verbose push ${REMOTE_NAME} --delete $(branch-from-remote-branch ${actual_remote}) + git-verbose push ${DEFAULT_UPSTREAM_REPOSITORY} --delete $(branch-from-remote-branch ${actual_remote}) fi fi } diff --git a/libexec/git-elegant-acquire-git b/libexec/git-elegant-acquire-git index 14227a7..02e496f 100755 --- a/libexec/git-elegant-acquire-git +++ b/libexec/git-elegant-acquire-git @@ -3,13 +3,13 @@ set -e command-purpose() { cat <\` is an Git URL to the repository to clone from (see +\`git clone --help\` for the details). + Approximate commands flow is \`\`\`bash ==>> git elegant clone-repository git@github.com:bees-hive/elegant-git.git diff --git a/libexec/git-elegant-deliver-work b/libexec/git-elegant-deliver-work index 2d638df..25c3e9a 100644 --- a/libexec/git-elegant-deliver-work +++ b/libexec/git-elegant-deliver-work @@ -3,7 +3,7 @@ set -e command-purpose() { cat <> git elegant deliver-work @@ -57,7 +60,7 @@ MESSAGE git-verbose rebase --continue else git-verbose fetch - git-verbose rebase ${RMASTER} + git-verbose rebase ${DEFAULT_REMOTE_TRACKING_BRANCH} fi local upstream=$(git branch --list --format "%(upstream:short)" ${1}) local branch=$(branch-from-remote-branch ${upstream}) @@ -69,7 +72,7 @@ MESSAGE branch=${1} fi if [[ -z "${remote}" ]]; then - remote=${REMOTE_NAME} + remote=${DEFAULT_UPSTREAM_REPOSITORY} fi git-verbose-op --open-urls-if-possible push --set-upstream --force ${remote} ${1}:${branch} } diff --git a/libexec/git-elegant-make-workflow b/libexec/git-elegant-make-workflow index 8ec03cf..1767cf4 100644 --- a/libexec/git-elegant-make-workflow +++ b/libexec/git-elegant-make-workflow @@ -2,7 +2,7 @@ command-purpose() { cat <\` is a name of Elegant Git command. + +A \`\` defines whether it should be executed \`ahead\` or \`after\` the given command. -And \`location\` defines the availability such as personal (located at +A \`\` defines the availability such as personal (located at \`.git/.workflows\`) or common (located at \`.workflows\`). - Approximate commands flow is \`\`\`bash ==>> git elegant make-workflow show-work ahead common diff --git a/libexec/git-elegant-obtain-work b/libexec/git-elegant-obtain-work index 4cb53a0..ab01697 100644 --- a/libexec/git-elegant-obtain-work +++ b/libexec/git-elegant-obtain-work @@ -3,28 +3,35 @@ set -e command-purpose() { cat < [local branch] +usage: git elegant obtain-work [local branch] MESSAGE } command-description() { cat<\` 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 \`\`\`bash -==>> git elegant obtain-work new-feature task-133 +==>> git elegant obtain-work 133 task-133 git fetch --all -git checkout -B task-133 custom-remote/new-feature +git checkout -B task-133 custom-remote/feature/133 \`\`\` MESSAGE } diff --git a/libexec/git-elegant-polish-work b/libexec/git-elegant-polish-work index ad47aa6..2d6d02e 100644 --- a/libexec/git-elegant-polish-work +++ b/libexec/git-elegant-polish-work @@ -3,7 +3,7 @@ set -e command-purpose() { cat < +usage: git elegant polish-workflow MESSAGE } @@ -17,6 +17,8 @@ command-description() { Opens a given workflow file in the default text editor. If given file is not present, the command raises an error. +A \`\` is a path to the desired workflow file. + Approximate commands flow is \`\`\`bash ==>> git elegant polish-workflow .workflows/show-work-ahead diff --git a/libexec/git-elegant-prune-repository b/libexec/git-elegant-prune-repository index 77630f2..371c421 100644 --- a/libexec/git-elegant-prune-repository +++ b/libexec/git-elegant-prune-repository @@ -16,12 +16,12 @@ MESSAGE command-description() { cat< | | ] +usage: git elegant show-release-notes [] [] [] MESSAGE } command-description() { cat<> git elegant show-work -git log --oneline ${MASTER}..@ +git log --oneline ${DEFAULT_BRANCH}..@ git status --short git stash list \`\`\` @@ -31,20 +31,20 @@ MESSAGE default(){ local branch=$(git rev-parse --abbrev-ref @) - info-text ">>> Work branch:" + info-text ">>> Branch refs:" info-text "local: ${branch}" local upstream=$(git rev-parse --abbrev-ref ${branch}@{upstream} 2>/dev/null || echo) if [[ -n ${upstream} ]]; then info-text "remote: ${upstream}" fi info-text "" - if [[ -n $(git rev-list ${MASTER}..${branch}) ]]; then - info-text ">>> New commits (comparing to 'master' branch):" - git log --oneline ${MASTER}..${branch} + if [[ -n $(git rev-list ${DEFAULT_BRANCH}..${branch}) ]]; then + info-text ">>> New commits (comparing to '${DEFAULT_BRANCH}' branch):" + git log --oneline ${DEFAULT_BRANCH}..${branch} info-text "" fi if [[ -n $(git status --short) ]]; then - info-text ">>> Unsaved modifications:" + info-text ">>> Uncommitted modifications:" git status --short info-text "" fi diff --git a/libexec/git-elegant-show-workflows b/libexec/git-elegant-show-workflows index 9b544b0..04e2a57 100644 --- a/libexec/git-elegant-show-workflows +++ b/libexec/git-elegant-show-workflows @@ -2,7 +2,7 @@ command-purpose() { cat <\` 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. @@ -34,14 +38,12 @@ git checkout -b task-123 git stash apply stash^{/elegant-git} git stash drop stash@{0} \`\`\` - -The command works even if a remote is unavailable. MESSAGE } --start-work-logic(){ source ${BINS}/plugins/state - local target=${2:-${MASTER}} + local target=${2:-${DEFAULT_BRANCH}} git-verbose checkout ${target} if is-there-upstream-for ${target}; then git-verbose pull || info-text "As the pull can't be completed, the current local version is used." diff --git a/libexec/plugins/pipe b/libexec/plugins/pipe index d435050..8b7b488 100644 --- a/libexec/plugins/pipe +++ b/libexec/plugins/pipe @@ -48,7 +48,7 @@ stash-pipe() { } branch-pipe() { - # Moves to the current branch after a command execution + # Moves to the current branch (HEAD) after a command execution # usage: branch-pipe [args]... # The pipe behavior is tested based on `release-work` command. That's why you # have to add new tests in `git-elegant-release-work.bats` if you want to diff --git a/workflows b/workflows index b8f2237..cea56b7 100755 --- a/workflows +++ b/workflows @@ -15,7 +15,7 @@ generate-docs() { preview-docs() { sleep 5 && open http://localhost:8000 & - mkdocs serve + python -m mkdocs serve } serve-docs() {