Added note about refresh and POSIX behavior (#648)

Co-authored-by: Martin Durant <[email protected]>

Author: rickmcgeer

gcsfs/core.py

@@ -210,7 +210,14 @@ class GCSFileSystem(asyn.AsyncFileSystem):
     GCSFileSystem maintains a per-implied-directory cache of object listings and
     fulfills all object information and listing requests from cache. This implied, for example, that objects
     created via other processes *will not* be visible to the GCSFileSystem until the cache
-    refreshed. Calls to GCSFileSystem.open and calls to GCSFile are not effected by this cache.
+    refreshed. Calls to GCSFileSystem.open and calls to GCSFile are not affected by this cache.
+
+    Note that directory listings are cached by default, because fetching those listings can be expensive. This is
+    contrary to local filesystem behaviour. The cache will be cleared if writing from this instance, but it can
+    become stale and return incorrect results if the storage is written to from another process/machine.
+    If you anticipate this possibility, you can set the use_listings_cache and listings_expiry_time arguments
+    to configure the caching, call `.invalidate_cache()` when required, or pass `refresh=True` to the
+    various listing methods.
 
     In the default case the cache is never expired. This may be controlled via the ``cache_timeout``
     GCSFileSystem parameter or via explicit calls to ``GCSFileSystem.invalidate_cache``.