From 091a7f633c23a9d03d5975d619764f296d29431d Mon Sep 17 00:00:00 2001
From: Cameron Macintosh <jcmaci03@gmail.com>
Date: Thu, 4 Sep 2025 09:04:02 -0500
Subject: [PATCH 1/4] docs: Better document operations in "Basic" mode.

---
 cls/SourceControl/Git/Utils.cls | 12 ++++++++++--
 docs/menu-items.md              | 13 +++++++++++--
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/cls/SourceControl/Git/Utils.cls b/cls/SourceControl/Git/Utils.cls
index 1ff0b905..b05073ef 100644
--- a/cls/SourceControl/Git/Utils.cls
+++ b/cls/SourceControl/Git/Utils.cls
@@ -414,6 +414,10 @@ ClassMethod Commit(InternalName As %String, Message As %String = "example commit
     quit $$$OK
 }
 
+/// <p>This function performs <code>git checkout -b [newBranchName]</code> from the current commit.</p>
+/// <p>If the user is in "Basic Mode" AND there is a Default Merge Branch defined,
+/// then this method first checks out and pulls that default merge branch before creating the new branch. This is
+/// equivalent to <code>git checkout [defaultMergeBranch] && git pull</code>.</p>
 ClassMethod NewBranch(newBranchName As %String) As %Status
 {
     set settings = ##class(SourceControl.Git.Settings).%New()
@@ -511,8 +515,12 @@ ClassMethod StageAddedFiles()
     }
 }
 
-/// Merges the files from the configured branch as part of the Sync operation
-/// Returns true if this resulted in durable changes to the local git repo
+/// <p>If there is a configured "Default Merge Branch", then
+/// <ol>
+///  <li>fetch the current version of the default merge branch.</li>
+///  <li>attempt to rebase the current branch onto the default merge branch.</li>
+/// </ol>
+/// Returns true if this resulted in durable changes to the local git repo, false otherwise.</p>
 ClassMethod MergeDefaultRemoteBranch(Output alert As %String = "") As %Boolean
 {
     set rebased = 0
diff --git a/docs/menu-items.md b/docs/menu-items.md
index e4e3007b..f2564e46 100644
--- a/docs/menu-items.md
+++ b/docs/menu-items.md
@@ -37,13 +37,22 @@ This also has the effect of refreshing the list of all remote branches and pruni
 Much like the [git pull](https://git-scm.com/docs/git-pull) command, this menu option pulls the most recent version of the current branch from a remote source, merging the changes into the local copy.
 
 ## Sync
-This option will synchronize a local repo with the remote repo. The sync operation is only enabled in basic mode. It encapsulates the pattern of fetching, pulling, committing and then pushing into one menu action. If there is no defined remote repository, it will simply commit any uncommitted files.
+This option will synchronize the current branch checked out a local repo with the same branch in a remote repo.  It encapsulates the pattern of fetching, pulling, committing, and pushing into one menu action.
+- If you are on the Default Merge Branch, then Sync only pulls the latest commits from the remote.  Committing is disallowed on the Default Merge Branch.
+- If there is no defined remote repository, it will simply commit any uncommitted files.
+- If there is a Default Merge Branch defined, then sync attempts to perform a rebase onto the latest Default Merge Branch from the remote.
+    - If the rebase were to result in merge conflicts, then this action is aborted so the system is not left in an inconsistent state.
+
+
+The sync operation is only enabled in basic mode.
 
 ## Create new branch
 This menu option creates a new branch in the repository for changes to be committed to. It also changes the current branch to be the created branch. This mimics the behavior of the [git checkout -b](https://git-scm.com/docs/git-checkout) command.
 
+In basic mode, this option first checks out the Default Merge Branch (if defined) and pulls that branch from the remote before creating the new branch.
+
 ## Check out an existing branch
-This option refreshes the local list of branches available in the upstream repository, and then changes the currently checkedout branch to the provided branch.  This mimics the behavior of the [git fetch --prune](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---prune) and [git checkout](https://git-scm.com/docs/git-checkout) commands.
+This option refreshes the local list of branches available in the upstream repository, and then changes the currently checked out branch to the provided branch.  This mimics the behavior of the [git fetch --prune](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---prune) and [git checkout](https://git-scm.com/docs/git-checkout) commands.
 
 If the desired branch does not exist in your local or in the remote, then you will receive the "Selected branch does not exist" error message.
 

From 8587a4a3bb9b6f2e21a4c628b96993478a0f3df0 Mon Sep 17 00:00:00 2001
From: Cameron Macintosh <jcmaci03@gmail.com>
Date: Thu, 4 Sep 2025 09:10:21 -0500
Subject: [PATCH 2/4] docs: Hyperlink to git-rebase docs for reference.

---
 docs/menu-items.md | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/docs/menu-items.md b/docs/menu-items.md
index f2564e46..7e83e2f0 100644
--- a/docs/menu-items.md
+++ b/docs/menu-items.md
@@ -3,6 +3,7 @@
 ## Status
 This menu option is analogous to the [git status](https://git-scm.com/docs/git-status) command and prints the status of the repository to the output.
 
+
 ## Settings
 This option opens the GUI's settings page project specific git-source-control settings can be configured. This includes the settings that were configured when running:
 ```
@@ -13,57 +14,70 @@ This page also includes the mappings configurations.
 
 Any changes made to the settings must be saved using the 'Save' button in order to take effect.
 
+
 ## Launch Git UI
 This menu option opens the git-source-control GUI. From here commit messages can be written, files can be staged and committed, branches can be viewed.
 
+
 ## Add
 This menu option is analogous to the [git add](https://git-scm.com/docs/git-add) command. It will perform 'git add' on the currently open file, adding it to the files that can be staged.
 
+
 ## Remove
 This menu option will only appear if the currently open file has been already added using the 'Add' menu option. It undoes the effect of adding the file, similar to running [git reset](https://git-scm.com/docs/git-reset) on a specific file.
 
+
 ## Push to remote branch
 This option pushes the commits in the branch to the remote repository. This exhibits the same behavior as the [git push](https://git-scm.com/docs/git-push) command.
 
+
 ## Push to remote branch (force)
 This option forcibly pushes the commits in the branch to the remote repository. This is potentially destructive and may overwrite the commit history of the remote branch. This exhibits the same behavior as the [git push --force](https://git-scm.com/docs/git-push) command.
 
+
 ## Fetch from remote
 This option first [fetches](https://git-scm.com/docs/git-fetch) the most recent version of the branch without merging that version into the local copy of the branch.  It will then list all files modified between the current version and the remote version.
 
 This also has the effect of refreshing the list of all remote branches and pruning any references that no longer exist in the remote.  (see: [git fetch --prune](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---prune))
 
+
 ## Pull changes from remote branch
 Much like the [git pull](https://git-scm.com/docs/git-pull) command, this menu option pulls the most recent version of the current branch from a remote source, merging the changes into the local copy.
 
+
 ## Sync
 This option will synchronize the current branch checked out a local repo with the same branch in a remote repo.  It encapsulates the pattern of fetching, pulling, committing, and pushing into one menu action.
 - If you are on the Default Merge Branch, then Sync only pulls the latest commits from the remote.  Committing is disallowed on the Default Merge Branch.
 - If there is no defined remote repository, it will simply commit any uncommitted files.
-- If there is a Default Merge Branch defined, then sync attempts to perform a rebase onto the latest Default Merge Branch from the remote.
+- If there is a Default Merge Branch defined, then sync attempts to perform a [rebase](https://git-scm.com/docs/git-rebase) onto the latest Default Merge Branch from the remote.
     - If the rebase were to result in merge conflicts, then this action is aborted so the system is not left in an inconsistent state.
 
-
 The sync operation is only enabled in basic mode.
 
+
 ## Create new branch
 This menu option creates a new branch in the repository for changes to be committed to. It also changes the current branch to be the created branch. This mimics the behavior of the [git checkout -b](https://git-scm.com/docs/git-checkout) command.
 
 In basic mode, this option first checks out the Default Merge Branch (if defined) and pulls that branch from the remote before creating the new branch.
 
+
 ## Check out an existing branch
 This option refreshes the local list of branches available in the upstream repository, and then changes the currently checked out branch to the provided branch.  This mimics the behavior of the [git fetch --prune](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---prune) and [git checkout](https://git-scm.com/docs/git-checkout) commands.
 
 If the desired branch does not exist in your local or in the remote, then you will receive the "Selected branch does not exist" error message.
 
+
 ## Export all
 This option exports class files to the local file tree at the configured location.
 
+
 ## Export all (force)
 This option exports all class files regardless of whether they're already up to date in the local file tree or not.
 
+
 ## Import all
 This option imports the versions of the files that are found in the configured directory into the project. Files that are out of date or the same as the files in the project won't be imported.
 
+
 ## Import all (force)
 This menu option behaves similarly to the regular import but forces the files to be imported regardless of whether the on-disk version is the same or older.

From 9800861a293b11b0da18f28ee1442a520d83f454 Mon Sep 17 00:00:00 2001
From: Cameron Macintosh <jcmaci03@gmail.com>
Date: Thu, 4 Sep 2025 09:14:11 -0500
Subject: [PATCH 3/4] docs: change casing of headers.

---
 docs/menu-items.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/menu-items.md b/docs/menu-items.md
index 7e83e2f0..251098e2 100644
--- a/docs/menu-items.md
+++ b/docs/menu-items.md
@@ -27,21 +27,21 @@ This menu option is analogous to the [git add](https://git-scm.com/docs/git-add)
 This menu option will only appear if the currently open file has been already added using the 'Add' menu option. It undoes the effect of adding the file, similar to running [git reset](https://git-scm.com/docs/git-reset) on a specific file.
 
 
-## Push to remote branch
+## Push to Remote Branch
 This option pushes the commits in the branch to the remote repository. This exhibits the same behavior as the [git push](https://git-scm.com/docs/git-push) command.
 
 
-## Push to remote branch (force)
+## Push to Remote Branch (force)
 This option forcibly pushes the commits in the branch to the remote repository. This is potentially destructive and may overwrite the commit history of the remote branch. This exhibits the same behavior as the [git push --force](https://git-scm.com/docs/git-push) command.
 
 
-## Fetch from remote
+## Fetch from Remote
 This option first [fetches](https://git-scm.com/docs/git-fetch) the most recent version of the branch without merging that version into the local copy of the branch.  It will then list all files modified between the current version and the remote version.
 
 This also has the effect of refreshing the list of all remote branches and pruning any references that no longer exist in the remote.  (see: [git fetch --prune](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---prune))
 
 
-## Pull changes from remote branch
+## Pull Changes from Remote Branch
 Much like the [git pull](https://git-scm.com/docs/git-pull) command, this menu option pulls the most recent version of the current branch from a remote source, merging the changes into the local copy.
 
 
@@ -55,29 +55,29 @@ This option will synchronize the current branch checked out a local repo with th
 The sync operation is only enabled in basic mode.
 
 
-## Create new branch
+## Create New Branch
 This menu option creates a new branch in the repository for changes to be committed to. It also changes the current branch to be the created branch. This mimics the behavior of the [git checkout -b](https://git-scm.com/docs/git-checkout) command.
 
 In basic mode, this option first checks out the Default Merge Branch (if defined) and pulls that branch from the remote before creating the new branch.
 
 
-## Check out an existing branch
+## Check Out an Existing Branch
 This option refreshes the local list of branches available in the upstream repository, and then changes the currently checked out branch to the provided branch.  This mimics the behavior of the [git fetch --prune](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---prune) and [git checkout](https://git-scm.com/docs/git-checkout) commands.
 
 If the desired branch does not exist in your local or in the remote, then you will receive the "Selected branch does not exist" error message.
 
 
-## Export all
+## Export All
 This option exports class files to the local file tree at the configured location.
 
 
-## Export all (force)
+## Export All (Force)
 This option exports all class files regardless of whether they're already up to date in the local file tree or not.
 
 
-## Import all
+## Import All
 This option imports the versions of the files that are found in the configured directory into the project. Files that are out of date or the same as the files in the project won't be imported.
 
 
-## Import all (force)
+## Import All (Force)
 This menu option behaves similarly to the regular import but forces the files to be imported regardless of whether the on-disk version is the same or older.

From ede203bdc1649f292841e2e0377b139fff0e0428 Mon Sep 17 00:00:00 2001
From: Cameron Macintosh <jcmaci03@gmail.com>
Date: Thu, 4 Sep 2025 12:19:59 -0500
Subject: [PATCH 4/4] docs: Clarify that Sync commits all staged files just in
 case advanced users are editing other files directly in the git checkout.

---
 docs/menu-items.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/menu-items.md b/docs/menu-items.md
index 251098e2..08030f6c 100644
--- a/docs/menu-items.md
+++ b/docs/menu-items.md
@@ -48,7 +48,7 @@ Much like the [git pull](https://git-scm.com/docs/git-pull) command, this menu o
 ## Sync
 This option will synchronize the current branch checked out a local repo with the same branch in a remote repo.  It encapsulates the pattern of fetching, pulling, committing, and pushing into one menu action.
 - If you are on the Default Merge Branch, then Sync only pulls the latest commits from the remote.  Committing is disallowed on the Default Merge Branch.
-- If there is no defined remote repository, it will simply commit any uncommitted files.
+- If there is no defined remote repository, it will simply commit all staged files.
 - If there is a Default Merge Branch defined, then sync attempts to perform a [rebase](https://git-scm.com/docs/git-rebase) onto the latest Default Merge Branch from the remote.
     - If the rebase were to result in merge conflicts, then this action is aborted so the system is not left in an inconsistent state.