feat: add git_new_feature function

Signed-off-by: Sebastian Davids <[email protected]>

docs/user-guide/modules/ROOT/nav.adoc

@@ -100,6 +100,7 @@
 *** xref:functions/general/color-stderr.adoc[]
 *** xref:functions/general/ls-extensions.adoc[]
 ** xref:functions/git/git.adoc[]
+*** xref:functions/git/git-new-feature.adoc[]
 *** xref:functions/git/ls-extensions-git.adoc[]
 ** xref:functions/gh/gh.adoc[]
 *** xref:functions/gh/repo-new-gh.adoc[]

docs/user-guide/modules/ROOT/pages/functions/git/git-new-feature.adoc

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: © 2024 Sebastian Davids <[email protected]>
+// SPDX-License-Identifier: Apache-2.0
+= git_new_feature
+:function_url: https://github.com/sdavids/sdavids-shell-misc/blob/main/zfunc/git_new_feature
+
+{function_url}[This function^] will create and switch to a new https://martinfowler.com/bliki/FeatureBranch.html[feature branch] with the given name.
+
+The optional second parameter is the https://git-scm.com/docs/git-branch#Documentation/git-branch.txt-ltstart-pointgt[start point] (`main` if not given) for the feature branch.
+
+The optional third parameter is the https://git-scm.com/docs/git-push#Documentation/git-push.txt---set-upstream[upstream] (`origin` if not given) for the feature branch.
+
+[NOTE]
+====
+The created feature branch will be pushed to the upstream if possible.
+====
+
+[TIP]
+====
+Set the following Git configuration variables on your repository if you want to use a https://git-scm.com/book/en/v2/Git-Branching-Rebasing[rebase workflow]:
+
+[,shell]
+----
+$ git config branch.autosetuprebase always
+$ git config --bool pull.rebase true
+----
+
+Or set it globally:
+
+[,shell]
+----
+$ git config --global branch.autosetuprebase always
+$ git config --global --bool pull.rebase true
+----
+
+More Information:
+
+* https://git-scm.com/docs/git-config.html#Documentation/git-config.txt-branchautoSetupRebase[branch.autoSetupRebase]
+* https://git-scm.com/docs/git-config.html#Documentation/git-config.txt-pullrebase[pull.rebase]
+
+====
+
+== Usage
+
+[,shell]
+----
+$ git_new_feature issue-1
+$ git branch -vv
+* issue-1 5a669af [origin/issue-1] initial
+  main    5a669af [origin/main] initial
+$ git log --oneline
+5a669af (HEAD -> issue-1, origin/main, origin/issue-1, main) initial
+
+$ touch work
+$ git add work
+$ git commit --quiet -m work
+$ git push --quiet
+$ git log --oneline
+2baf87f (HEAD -> issue-1, origin/issue-1) work
+5a669af (origin/main, main) initial
+
+$ git_new_feature stacked issue-1
+$ git branch -vv
+  issue-1 2baf87f [origin/issue-1] work
+  main    5a669af [origin/main] initial
+* stacked 2baf87f [origin/stacked] work
+$ git log --oneline
+2baf87f (HEAD -> stacked, origin/stacked, origin/issue-1, issue-1) work
+5a669af (origin/main, main) initial
+
+$ git_new_feature issue-2 main upstream
+$ git branch -vv
+* issue-2 5a669af [upstream/another] initial
+  issue-1 2baf87f [origin/issue-1] work
+  main    5a669af [origin/main] initial
+  stacked 2baf87f [origin/stacked] work
+$ git log --oneline
+5a669af (HEAD -> another, upstream/another, origin/main, main) initial
+----
+
+== More Information
+
+* https://git-scm.com/book/en/v2/Git-Branching-Rebasing[Git Branching - Rebasing]
+* https://www.git-tower.com/blog/stacked-prs/[Stacked Pull Requests Workflow]
+* https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request[GitHub - Pull Request]

docs/user-guide/modules/ROOT/pages/functions/git/git.adoc

@@ -4,6 +4,7 @@
 
 This section contains functions related to https://git-scm.com[Git]:
 
+xref:functions/git/git-new-feature.adoc[]:: create a new feature branch
 xref:functions/git/ls-extensions-git.adoc[]:: display all file extensions for tracked files
 
 Related: xref:scripts/git/git.adoc[Git Scripts]

zfunc/git_new_feature

@@ -0,0 +1,39 @@
+# vim:ft=zsh
+
+# shellcheck shell=sh
+
+# SPDX-FileCopyrightText: © 2025 Sebastian Davids <[email protected]>
+# SPDX-License-Identifier: Apache-2.0
+
+# this function needs to be placed in a $FPATH directory
+#
+# add the following to your $ZDOTDIR/.zshrc:
+#
+# autoload -Uz "git_new_feature"
+#
+
+git_new_feature() {
+  if [ -z "$*" ]; then
+    echo "Usage: $0 FEATURE_NAME [START_POINT] [UPSTREAM]" >&2
+  else
+    if [ "$(git rev-list --count --all)" -eq 0 ]; then
+      echo "Cannot create a feature in a pristine repository" >&2
+    else
+      feature_name="$1"
+      start_point="${2:-main}"
+      upstream="${3:-origin}"
+
+      upstream_url="$(git remote get-url "${upstream}" 2>/dev/null || echo '')"
+      if [ -n "${upstream_url}" ]; then
+        git checkout -b "${feature_name}" --no-track "${start_point}"
+        # shellcheck disable=SC2181
+        if [ $? -eq 0 ]; then
+          git pull --rebase "${upstream}" "${start_point}" 2>/dev/null
+          git push --set-upstream "${upstream}" "${feature_name}"
+        fi
+      else
+        git checkout -b "${feature_name}" "${start_point}"
+      fi
+    fi
+  fi
+}