1This is Info file cvsclient.info, produced by Makeinfo version 1.67 2from the input file ./cvsclient.texi. 3 4 5File: cvsclient.info, Node: Example, Next: Requirements, Prev: Text tags, Up: Protocol 6 7Example 8======= 9 10 Here is an example; lines are prefixed by `C: ' to indicate the 11client sends them or `S: ' to indicate the server sends them. 12 13 The client starts by connecting, sending the root, and completing the 14protocol negotiation. In actual practice the lists of valid responses 15and requests would be longer. 16 17 C: Root /u/cvsroot 18 C: Valid-responses ok error Checked-in M E 19 C: valid-requests 20 S: Valid-requests Root Directory Entry Modified Argument Argumentx ci co 21 S: ok 22 C: UseUnchanged 23 24 The client wants to check out the `supermunger' module into a fresh 25working directory. Therefore it first expands the `supermunger' 26module; this step would be omitted if the client was operating on a 27directory rather than a module. 28 29 C: Argument supermunger 30 C: Directory . 31 C: /u/cvsroot 32 C: expand-modules 33 34 The server replies that the `supermunger' module expands to the 35directory `supermunger' (the simplest case): 36 37 S: Module-expansion supermunger 38 S: ok 39 40 The client then proceeds to check out the directory. The fact that 41it sends only a single `Directory' request which specifies `.' for the 42working directory means that there is not already a `supermunger' 43directory on the client. 44 45 C: Argument -N 46 C: Argument supermunger 47 C: Directory . 48 C: /u/cvsroot 49 C: co 50 51 The server replies with the requested files. In this example, there 52is only one file, `mungeall.c'. The `Clear-sticky' and 53`Clear-static-directory' requests are sent by the current 54implementation but they have no effect because the default is for those 55settings to be clear when a directory is newly created. 56 57 S: Clear-sticky supermunger/ 58 S: /u/cvsroot/supermunger/ 59 S: Clear-static-directory supermunger/ 60 S: /u/cvsroot/supermunger/ 61 S: E cvs server: Updating supermunger 62 S: M U supermunger/mungeall.c 63 S: Created supermunger/ 64 S: /u/cvsroot/supermunger/mungeall.c 65 S: /mungeall.c/1.1/// 66 S: u=rw,g=r,o=r 67 S: 26 68 S: int mein () { abort (); } 69 S: ok 70 71 The current client implementation would break the connection here 72and make a new connection for the next command. However, the protocol 73allows it to keep the connection open and continue, which is what we 74show here. 75 76 After the user modifies the file and instructs the client to check it 77back in. The client sends arguments to specify the log message and file 78to check in: 79 80 C: Argument -m 81 C: Argument Well, you see, it took me hours and hours to find 82 C: Argumentx this typo and I searched and searched and eventually 83 C: Argumentx had to ask John for help. 84 C: Argument mungeall.c 85 86 It also sends information about the contents of the working 87directory, including the new contents of the modified file. Note that 88the user has changed into the `supermunger' directory before executing 89this command; the top level directory is a user-visible concept because 90the server should print filenames in `M' and `E' responses relative to 91that directory. 92 93 C: Directory . 94 C: /u/cvsroot/supermunger 95 C: Entry /mungeall.c/1.1/// 96 C: Modified mungeall.c 97 C: u=rw,g=r,o=r 98 C: 26 99 C: int main () { abort (); } 100 101 And finally, the client issues the checkin command (which makes use 102of the data just sent): 103 104 C: ci 105 106 And the server tells the client that the checkin succeeded: 107 108 S: M Checking in mungeall.c; 109 S: E /u/cvsroot/supermunger/mungeall.c,v <-- mungeall.c 110 S: E new revision: 1.2; previous revision: 1.1 111 S: E done 112 S: Mode u=rw,g=r,o=r 113 S: Checked-in ./ 114 S: /u/cvsroot/supermunger/mungeall.c 115 S: /mungeall.c/1.2/// 116 S: ok 117 118 119File: cvsclient.info, Node: Requirements, Next: Obsolete, Prev: Example, Up: Protocol 120 121Required versus optional parts of the protocol 122============================================== 123 124 The following are part of every known implementation of the CVS 125protocol (except obsolete, pre-1.5, versions of CVS) and it is 126considered reasonable behavior to completely fail to work if you are 127connected with an implementation which attempts to not support them. 128Requests: `Root', `Valid-responses', `valid-requests', `Directory', 129`Entry', `Modified', `Unchanged', `Argument', `Argumentx', `ci', `co', 130`update'. Responses: `ok', `error', `Valid-requests', `Checked-in', 131`Updated', `Merged', `Removed', `M', `E'. 132 133 A server need not implement `Repository', but in order to 134interoperate with CVS 1.5 through 1.9 it must claim to implement it (in 135`Valid-requests'). The client will not actually send the request. 136 137 138File: cvsclient.info, Node: Obsolete, Prev: Requirements, Up: Protocol 139 140Obsolete protocol elements 141========================== 142 143 This section briefly describes protocol elements which are obsolete. 144There is no attempt to document them in full detail. 145 146 There was a `Repository' request which was like `Directory' except 147it only provided REPOSITORY, and the local directory was assumed to be 148similarly named. 149 150 If the `UseUnchanged' request was not sent, there was a `Lost' 151request which was sent to indicate that a file did not exist in the 152working directory, and the meaning of sending `Entries' without `Lost' 153or `Modified' was different. All current clients (CVS 1.5 and later) 154will send `UseUnchanged' if it is supported. 155 156 157File: cvsclient.info, Node: Protocol Notes, Prev: Protocol, Up: Top 158 159Notes on the Protocol 160********************* 161 162 A number of enhancements are possible. Also see the file TODO in 163the CVS source distribution, which has further ideas concerning various 164aspects of CVS, some of which impact the protocol. 165 166 * The `Modified' request could be speeded up by sending diffs rather 167 than entire files. The client would need some way to keep the 168 version of the file which was originally checked out; probably 169 requiring the use of "cvs edit" in this case is the most sensible 170 course (the "cvs edit" could be handled by a package like VC for 171 emacs). This would also allow local operation of `cvs diff' 172 without arguments. 173 174 * The current procedure for `cvs update' is highly sub-optimal if 175 there are many modified files. One possible alternative would be 176 to have the client send a first request without the contents of 177 every modified file, then have the server tell it what files it 178 needs. Note the server needs to do the what-needs-to-be-updated 179 check twice (or more, if changes in the repository mean it has to 180 ask the client for more files), because it can't keep locks open 181 while waiting for the network. Perhaps this whole thing is 182 irrelevant if there is a multisite capability (as noted in TODO), 183 and therefore the rcsmerge can be done with a repository which is 184 connected via a fast connection. 185 186 * The fact that `pserver' requires an extra network turnaround in 187 order to perform authentication would be nice to avoid. This 188 relates to the issue of reporting errors; probably the clean 189 solution is to defer the error until the client has issued a 190 request which expects a response. To some extent this might 191 relate to the next item (in terms of how easy it is to skip a 192 whole bunch of requests until we get to one that expects a 193 response). I know that the kerberos code doesn't wait in this 194 fashion, but that probably can cause network deadlocks and perhaps 195 future problems running over a transport which is more transaction 196 oriented than TCP. On the other hand I'm not sure it is wise to 197 make the client conduct a lengthy upload only to find there is an 198 authentication failure. 199 200 * The protocol uses an extra network turnaround for protocol 201 negotiation (`valid-requests'). It might be nice to avoid this by 202 having the client be able to send requests and tell the server to 203 ignore them if they are unrecognized (different requests could 204 produce a fatal error if unrecognized). To do this there should 205 be a standard syntax for requests. For example, perhaps all 206 future requests should be a single line, with mechanisms analogous 207 to `Argumentx', or several requests working together, to provide 208 greater amounts of information. Or there might be a standard 209 mechanism for counted data (analogous to that used by `Modified') 210 or continuation lines (like a generalized `Argumentx'). It would 211 be useful to compare what HTTP is planning in this area; last I 212 looked they were contemplating something called Protocol Extension 213 Protocol but I haven't looked at the relevant IETF documents in 214 any detail. Obviously, we want something as simple as possible 215 (but no simpler). 216 217 * The scrambling algorithm in the CVS client and server actually 218 support more characters than those documented in *Note Password 219 scrambling::. Someday we are going to either have to document 220 them all (but this is not as easy as it may look, see below), or 221 (gradually and with adequate process) phase out the support for 222 other characters in the CVS implementation. This business of 223 having the feature partly undocumented isn't a desirable state 224 long-term. 225 226 The problem with documenting other characters is that unless we 227 know what character set is in use, there is no way to make a 228 password portable from one system to another. For example, a with 229 a circle on top might have different encodings in different 230 character sets. 231 232 It *almost* works to say that the client picks an arbitrary, 233 unknown character set (indeed, having the CVS client know what 234 character set the user has in mind is a hard problem otherwise), 235 and scrambles according to a certain octet<->octet mapping. There 236 are two problems with this. One is that the protocol has no way 237 to transmit character 10 decimal (linefeed), and the current 238 server and clients have no way to handle 0 decimal (NUL). This 239 may cause problems with certain multibyte character sets, in which 240 octets 10 and 0 will appear in the middle of other characters. 241 The other problem, which is more minor and possibly not worth 242 worrying about, is that someone can type a password on one system 243 and then go to another system which uses a different encoding for 244 the same characters, and have their password not work. 245 246 The restriction to the ISO646 invariant subset is the best 247 approach for strings which are not particularly significant to 248 users. Passwords are visible enough that this is somewhat 249 doubtful as applied here. ISO646 does, however, have the virtue 250 (!?) of offending everyone. It is easy to say "But the $ is right 251 on people's keyboards! Surely we can't forbid that". From a 252 human factors point of view, that makes quite a bit of sense. The 253 contrary argument, of course, is that a with a circle on top, or 254 some of the characters poorly handled by Unicode, are on 255 *someone*'s keyboard. 256 257 258