[SvnBook] #78: ch03 should have a section on use of --depth

[SvnBook]

#78: ch03 should have a section on use of --depth
----------------------+-----------------------------------------------------
  Reporter:  sussman  |       Owner:  cmpilato
      Type:  task     |      Status:  new     
  Priority:  normal   |   Milestone:  1.5     
 Component:  content  |     Version:          
Resolution:           |    Keywords:          
----------------------+-----------------------------------------------------
Comment (by cmpilato):

 Here's the outline of the sparse directories talk I gave at SubConf.
 Maybe something in here will be of use

 ----

 What Is It?
  * Subversion 1.5 feature
  * Means of controlling working copy population
    * Based on directory tree depth selection
    * Selected depth is "sticky" - maintained across operations
  * Client-side, per-working-copy
  * Known by many names...
    * "sparse directories"
    * "selective checkouts"
    * "shallow checkouts"
    * "issue 695"
    * "non-recursive checkouts actually work"

 What It Isn't
  * Generic working copy bootstrap/assembly  mechanism (viewspecs)
  * Versioned or otherwise shareable  between working copies

 Why?
  * `svn checkout --non-recursive' is  famously broken and misconceived
    * Non-recursiveness isn't sticky
    * Client's ignorance -> server's ignorance -> confusing errors
    * Only needing to edit files in the top-level of  some tree is not
 exactly the common case...
  * Sometimes you just don't care to keep  some subset of your project
 around locally
    * Modules you never edit (www/ ?)
    * Large files kept alongside source code
      * Build environments (OS images, ISO images...)
      * Build artifacts (release binaries...)
      * Large datasets for stress and regression testing
  * Many projects living in a single  repository, where only a subset of
 them matter to you
    * Common deployment scenario (ASF, KDE, many others)
    * Common layout when using IDEs (many sibling projects in a single
 directory)

 The Mechanics
  * New --depth option for checkout and  update
    * Supercedes --recursive (-R) and --non-recursive  (-N) options
    * Values
      * "empty": only the named target(s)
      * "files": only the named target(s) and, if directories,  their
 immediate file children
      * "immediates": only the named target(s) and, if  directories, their
 immediate children (where  directory children are themselves empty)
      * "infinity": full recursion
  * Depth is maintained unless specifically  changed
    * `svn update' doesn't add stuff you didn't want
    * `svn update --depth NEWDEPTH' tweaks the  depth
      * pulls down now-wanted stuff from the server
      * removes now-unwanted stuff from the working copy

 Example 1: Ignoring a Module
  * Before 1.5:
 {{{
 $ svn co http://svn.collab.net/repos/svn/trunk
 $ cd trunk
 $ rm -rf www
 $ svn up        # Oops!  trunk/www is restored!
 }}}
  * Using 1.5:
 {{{
 $ svn co --depth files  http://svn.collab.net/repos/svn/trunk
 $ cd trunk
 $ svn up --depth infinity build contrib docs ...  # not www
 $ svn up        # Nice!  Still no www directory!
 }}}

 Example 2: Checkout -N
  * Before 1.5:
 {{{
 $ svn co -N http://svn.collab.net/repos/svn/trunk
 $  cd trunk
 # someone commits deletion of directory you don't have
 $ svn up        # Gack!  Server tells client to delete something it
 doesn't even have = error!
 }}}
  * Using 1.5:
 {{{
 $ svn co -N http://svn.collab.net/repos/svn/trunk
 $ cd trunk
 # someone commits deletion of directory you don't have
 $ svn up        # No sweat - server doesn't tell you what you don't need
 to know
 }}}

 Notes
  * Does not require Subversion 1.5 server
    * When requesting depths of older servers, the  client just filters out
 out-of-scope data
    * It's slow, but correct
  * Interaction with externals definitions is  awkward
    * svn:externals only included when referring  directory has depth
 infinity
  * New --depth replaces --recursive and --non-recursive universally

-- 
Ticket URL: <http://svnbook.red-bean.com/trac/ticket/78#comment:2>
SvnBook <http://svnbook.red-bean.com/>