docs: Better document operations in "Basic" mode.

Author: cambot

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

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.