avoid unnecessary checkout, more docs content

3 files changed, 58 insertions, 18 deletions

diff --git a/awx/main/tasks.py b/awx/main/tasks.py
index 8c5fd1f712..a6d5937361 100644
--- a/awx/main/tasks.py
+++ b/awx/main/tasks.py
@@ -2058,7 +2058,8 @@ class RunProjectUpdate(BaseTask):
             os.mkdir(settings.PROJECTS_ROOT)
         self.acquire_lock(instance)
         self.original_branch = None
-        if instance.scm_type == 'git' and instance.job_type == 'run' and instance.project:
+        if (instance.scm_type == 'git' and instance.job_type == 'run' and instance.project and
+                instance.scm_branch != instance.project.scm_branch):
             project_path = instance.project.get_project_path(check_if_exists=False)
             if os.path.exists(project_path):
                 git_repo = git.Repo(project_path)
diff --git a/awx/ui/client/src/projects/projects.form.js b/awx/ui/client/src/projects/projects.form.js
index 41f1e6aed5..3ba529749e 100644
--- a/awx/ui/client/src/projects/projects.form.js
+++ b/awx/ui/client/src/projects/projects.form.js
@@ -139,7 +139,7 @@ export default ['i18n', 'NotificationsList', 'TemplateList',
                     '<p>' + i18n._('Examples include:') + '</p>' +
                     '</p><ul class=\"no-bullets\"><li>refs/*:refs/remotes/origin/*</li>' +
                     '<li>refs/pull/62/head:refs/remotes/origin/pull/62/head</li></ul>' +
-                    '<p>' + i18n._('The first fetches all references.  The second fetches only the Github pull request number 62, in this example the branch needs to be `refs/pull/62/head`.') +
+                    '<p>' + i18n._('The first fetches all references.  The second fetches the Github pull request number 62, in this example the branch needs to be `pull/62/head`.') +
                     '</p>' +
                     '<p>' + i18n._('For more information, refer to the') + '<a target="_blank" href="https://docs.ansible.com/ansible-tower/latest/html/userguide/projects.html#manage-playbooks-using-source-control"> ' + i18n._('Ansible Tower Documentation') + '</a>.</p>',
                 dataTitle: i18n._('SCM Refspec'),
diff --git a/docs/job_branch_override.md b/docs/job_branch_override.md
index de96752b04..322f8ab86b 100644
--- a/docs/job_branch_override.md
+++ b/docs/job_branch_override.md
@@ -1,9 +1,9 @@
-## Job Branch Specification
+## Job Branch Override
 
-Background: Projects specify the branch to use from source control
+Background: Projects specify the branch, tag, or reference to use from source control
 in the `scm_branch` field.
 
-This feature allows project admins to delegate branch selection to
+This "Branch Override" feature allows project admins to delegate branch selection to
 admins of job templates that use that project (requiring only project
 `use_role`). Admins of job templates can further
 delegate that ability to users executing the job template
@@ -12,15 +12,56 @@ delegate that ability to users executing the job template
 
 ### Source Tree Copy Behavior
 
-Every job run has its own private data directory. This folder is temporary,
-cleaned up at the end of the job run.
+Background: Every job run has its own private data directory.
+This folder is temporary, cleaned up at the end of the job run.
 
 This directory contains a copy of the project source tree for the given
-branch the job is running.
+`scm_branch` the job is running.
 
-A new copy is made for every job run.
+A new shallow copy is made for every job run.
+Jobs are free to make changes to the project folder and make use of those
+changes while it is still running.
 
-This folder will not contain the full git history for git project types.
+#### Use Cases That No Long Work
+
+With the introduction of this feature, the function of `scm_clean` is watered
+down. It will still be possible to enable this function, and it will be
+passed through as a parameter to the playbook as a tool for trouble shooting.
+Two notable cases that lose support are documented here.
+
+1) Setting `scm_clean` to `true` will no longer persist changes between job runs.
+
+That means that jobs that rely on content which is not committed to source
+control may fail now.
+
+2) Because it is a shallow copy, this folder will not contain the full
+git history for git project types.
+
+### Project Revision Concerns
+
+Background of how normal project updates work:
+The revision of the default branch (specified as `scm_branch` of the project)
+is stored when updated, and jobs using that project will employ this revision.
+
+Providing a non-default `scm_branch` in a job comes with some restrictions
+which are unlike the normal update behavior.
+If `scm_branch` is a branch identifier (not a commit hash or tag), then
+the newest revision is pulled from the source control remote immediately
+before the job starts.
+This revision is shown in the `scm_revision` field of the
+job and its respective project update.
+This means that offline job runs are impossible for non-default branches.
+To be sure that a job is running a static version from source control,
+use tags or commit hashes.
+
+Project updates do not save the revision of all branches, only the
+project default branch.
+
+The `scm_branch` field is not validated, so the project must update
+to assure it is valid.
+If `scm_branch` is provided or prompted for, the `playbook` field of
+job templates will not be validated, and users will have to launch
+the job template in order to verify presence of the expected playbook.
 
 ### Git Refspec
 
@@ -41,16 +82,14 @@ Examples:
  - `refs/pull/*:refs/remotes/origin/pull/*`
     Github-specific, this will fetch all refs for all pull requests
  - `refs/pull/62/head:refs/remotes/origin/pull/62/head`
-    This will fetch only the ref for that one github pull request
+    This will fetch the ref for that one github pull request
 
 For large projects, users should consider performance when
-using the first or second examples here. For example, if a github project
-has over 40,000 pull requests, that refspec will fetch them all
-during a project update.
+using the first or second examples here.
 
 This parameter affects availability of the project branch, and can allow
 access to references not otherwise available. For example, the third example
-will allow the user to use the branch `refs/pull/62/head`, which would
+will allow the user to supply `pull/62/head` for `scm_branch`, which would
 not be possible without the refspec field.
 
 The Ansible git module always fetches `refs/heads/*`. It will do this
@@ -59,8 +98,8 @@ branches and tags (and commit hashes therein) can be used as `scm_branch`
 no matter what is used for `scm_refspec`.
 
 The `scm_refspec` will affect which `scm_branch` fields can be used as overrides.
-For example, you could set up a project that allows branch override with a refspec
-of `refs/pull/*:refs/remotes/origin/pull/*`, then use this in a job template
+For example, you could set up a project that allows branch override with the
+1st or 2nd refspec example, then use this in a job template
 that prompts for `scm_branch`, then a client could launch the job template when
-a new pull request is created, providing the branch `refs/pull/N/head`,
+a new pull request is created, providing the branch `pull/N/head`,
 then the job template would run against the provided github pull request reference.