locking-ui.txt

subversion-1.4.3-1.tar.gz 配置svn的源码

A UI Specification for "Locking"

This document describes a user interface of a new locking system for
Subversion.  It implements the set of features described in the
associated functional spec.

I. Introduction

   A. Goals/Audience

      There are two audiences we need to consider for a locking UI:

      1. The enlightened software developer

         - understands general VC concepts (required for job)
         - understands concurrency model
         - has already embraced Subversion (or at least CVS)

         - ITCH: Some files aren't mergeable, like image files or
                 spreadsheets.  Need to force serialized edits on such
                 things, as an occasional exception to concurrency.

      2. The reluctant user of version control

         - bright people, but no time or interest in learning VC concepts
         - doesn't understand concurrency
         - doesn't understand "out-of-dateness" or merging procedures

         - typical examples:
            - coder who has only used VSS or Clearcase with 100% locking
            - website developer being forced to use VC
            - manager being forced to use VC

         - ITCH: VC system should be effortless, transparent, and
                 idiot proof.  VC system should prevent people from
                 wasting editing time, destroying each others
                 changes, all while avoiding concurrency concepts such
                 as "merging" and "out of dateness".


   B. The "Hijack" Scenario

       This is specific use-case which is particularly important to
       making version control usable by the second type of user
       described above.

       In this scenario, the user has a tool that circumvents whatever
       system is in place to enforce serialized editing.  In systems
       like VSS or Clearcase 'copy' views, this usually means an
       editor that ignores the read-only attribute on a file.  When
       the user goes to commit, they discover that they were supposed
       to lock the file, and the repository version has changed.  What
       now?

       The power-svn user would certainly have no problem knowing what
       to do seeing an error that "the file must be locked to commit",
       nor would such a user be confused by seeing a subsequent error
       that the "file is out-of-date".  The power user would run 'svn
       update', resolve conflicts, then lock the file and commit.

       But the reluctant or ignorant svn user shouldn't (and doesn't
       need to) be forced to deal with merging and out-of-dateness
       when working in an "all locking" environment.  Here are a few
       usability case-studies:

         - Clearcase dynamic views

             The workspace is always up-to-date, all of the time.  And
             it's impossible to circumvent the read-only bit.  So the
             hijack scenario can't happen at all.

         - Clearcase copy-based views
 
             In the hijack scenario, the user attempts to commit and
             the client responds by attempting an interactive
             contextual merge.  If not possible, the whole commit
             fails and a guru is phoned to fix the situation.

         - Visual Source Safe

             in the hijack scenario, the user remembers to lock the
             file long after editing it;  VSS asks whether to use the
             server version or local version of the file.  Somebody's
             edits are lost.

       It is the recommendation of this document that the command line
       client produce normal conflicts when 'svn up' is run on a
       hijacked file;  but that for a GUI such as TortoiseSVN, a more
       friendly (or interactive) procedure is followed -- perhaps one
       that allows the user to choose between versions of flies.


II. New Client Behaviors

   A. Overview

      This section describes a user interface to accomplish "locking",
      as described in the functional spec.  A new property is used to
      enforce locking and prevent people from wasting time; lock
      tokens are objects, stored in the working copy, that represent a
      lock; and two new subcommands (lock/unlock) are described.

   B. The "svn:needs-lock" property

      Create a new "svn:needs-lock" property to indicate that a file
      should be locked before committing.  Just like "svn:executable",
      the value of the property is irrelevant and the property can be
      created (or deleted) by any user or administrator.

      Note that this property doesn't enforce locking.

      When the Subversion client encounters the "svn:needs-lock"
      property on a path (on checkout or update), it sets the
      working-copy path to a read-only state by default.  This
      serves as a reminder to the user that she should lock this
      path before editing it.  When a user locks the path, the
      Subversion client makes the working-copy path read-write.
      When the user releases the lock, or if the lock is found to
      be defunct (see next section), the Subversion client makes
      the path read-only again.

   C. Lock manipulation via client

      1. Lock Tokens

         When a user successfully locks a path, the working copy
         receives a "lock token" from the server.  This token is an
         object that connects your exclusive right to commit to a path
         with your working copy.

         You can think of a lock token as a form of authentication for
         a certain working copy.  Why is it important or useful for
         lock tokens to be attached to only one working copy?

         [An example: you might lock an unmergeable file using a
         computer at your office, perhaps as part of a changeset in
         progress.  It should not be possible for a working copy on
         your home computer to accidentally commit a change to that
         same file, just because you've authenticated as the user
         which owns the lock.  If you really want to change the file
         from home, you'd have to "steal" the lock from your other
         working copy, which is discussed later in this document.]

         Because locks can be broken or stolen, it is possible for a
         lock token to become "defunct".  A defunct lock cannot be
         used or released--it is useless and is cleaned up when you
         next run 'svn update'.

      2. New client subcommands
          
         Summary:

              svn lock   [--force]:   lock (or steal)
              svn unlock [--force]:   release (or break)


         a. Creating a lock

            To lock a path, use the 'svn lock' command:

              $ svn lock foo.c
              username: harry
              password: XXXXX
              [...]
              'foo.c' locked by user 'harry'.
        
            In order for this command to work,

               - You *must* provide a username to the server.
                 'anonymous' locks are not allowed.
               - The path must not already be locked.
               - The path must not be out-of-date.  

            The lock command accepts -m or -F to add a lock comment, so
            others can see why the file was locked.  The lock comment
            is optional.

         b. Using a lock

            A lock can be used to make an exclusive commit to a path.
            Also, if you have a lock, you can opt to "release"
            (destroy) it when you're done.

            To make use of a lock, two forms of authentication must be
            provided to the server:

               - The authenticated username that owns the lock
               - A non-defunct lock token

            If either of these forms of authentication are missing or
            incorrect, the lock cannot be used.

            1. Using a lock to Commit

               $ svn commit foo.c
               
               Upon successful commit, a locked path is released by
               default.  The Subversion client provides an option to
               retain the lock after commit:

               $ svn commit foo.c --no-unlock

               If --no-unlock is not specified, even unmodified files
               will be considered part of the commit and shown to the
               user in the list of files to commit.  Such files will
               also be unlocked after the commit.

            2. Releasing a lock
 
               $ svn unlock foo.c
               Lock on 'foo.c' has been released.

               After successful release, the working copy's lock token
               is gone.

         c. Breaking a lock

            "Breaking" a lock is a means of releasing a lock when:

               - The authenticated username is not the same as the
                 lock owner, or
               - The working-copy lock representation is unavailable.

             Use the --force option to the unlock subcommand to
             break a lock.  For example:

             $ svn unlock foo.c
             username:  sally