A little more description of shallowness

1 files changed, 13 insertions, 3 deletions

diff --git a/testing/03-shallow-push.yarn b/testing/03-shallow-push.yarn
index dc029bd..ee8b4e0 100644
--- a/testing/03-shallow-push.yarn
+++ b/testing/03-shallow-push.yarn
@@ -3,18 +3,28 @@
 Pushing from shallow clones
 ===========================
 
+Git allows clones to be 'shallow' which means that they might not contain
+the full history, this means that you can work with a repository even though
+it might not contain everything in the history of all the refs.
+
     SCENARIO Pushing shallow history
 
     GIVEN a standard instance
      WHEN testinstance, using adminkey, clones gitano-admin.git as local-shallow with depth 1
 
-To push you need to set `git.receive.shallowUpdate=true`
-after the repository is created.
+In order to cause git to allow you to **send** it shallow content however, you
+need to set `git.receive.shallowUpdate=true` in the project configuration after
+the repository is created (which will set `receive.shallowUpdate=true` in the
+git `config` file).
 
     WHEN testinstance adminkey runs create remote-shallow.git
      AND testinstance adminkey runs config remote-shallow.git set git.receive.shallowUpdate true
 
-Then pushing shallow history succeeds.
+Once you have done that, you are permitted to push shallow content to the
+repository on the Gitano server.  **NOTE** do not do this for all repositories
+as it can result in information loss and even unusable git repositories if you
+are not super-careful.  Also you need to be careful to handle error cases when
+retrieving history if you have plugins or hooks on your Gitano server.
 
     WHEN testinstance, using adminkey, pushes local-shallow to remote-shallow.git
     THEN server-side remote-shallow.git file shallow exists