1Further options for FSVS.(1) fsvs Further options for FSVS.(1)
2
6 Further options for FSVS. - FSVS understands some other options, that
7 modify its behaviour.
8
10 FSVS currently knows:
11 · colordiff - Using colordiff
13 · commit_to - Destination URL for commit
14 · conflict - How to resolve conflicts on update
15 · copyfrom_exp - Avoiding expensive compares on copyfrom-detect
16 · debug_output - Destination for debug output
17 · delay - Waiting for a time change after working copy operations
18 · diff_prg, diff_opt, diff_extra - Options relating to the 'diff'
19 action
20 · dir_sort - Directory sorting
21 · empty_commit - Doing empty commits
22 · filter - Filtering entries, but see -f.
23 · log_output - 'fsvs log' output format
24 · merge_prg, merge_opt - Options regarding the 'merge' programm
25 · path - Displaying paths
26 · softroot - Using an alternate root directory
27 · stat_color - Status output coloring
28 · warning - Setting warning behaviour, but see -W.
30 The priorities are
31 · Command line (highest)
33 · Environment variables. These are named as FSVS_{upper-case option
34 name}.
35 · $HOME/.fsvs/wc-dir/config
36 · $FSVS_CONF/wc-dir/config
37 · $HOME/.fsvs/config
38 · $FSVS_CONF/config
39 · Default value, compiled in (lowest)
40 Note:
41 The $HOME-dependent configuration files are not implemented
42 currently. Volunteers?
43 Furthermore there are 'intelligent' run-time dependent settings, like
44 turning off colour output when the output is redirected. Their priority
45 is just below the command line - so they can always be overridden if
46 necessary.
48 Using the commandline:
49 fsvs -o path=environment
50 fsvs -opath=environment
51 Using environment variables:
53 FSVS_PATH=absolute fsvs st
54 A configuration file:
56 # FSVS configuration file
57 path=wcroot
58
60 You can specify how paths printed by FSVS should look like; this is
61 used for the entry status output of the various actions, and for the
62 diff header lines.
63 There are several possible settings, of which one can be chosen via the
64 path option.
65 ·
66 wcroot
67 This is the old, traditional FSVS setting, where all paths are
68 printed relative to the working copy root.
69 ·
70 parameter
71 With this setting FSVS works like most other programs - it uses the
72 first best-matching parameter given by the user, and appends the rest
73 of the path.
74 This is the new default.
75 Note:
76 Internally FSVS still first parses all arguments, and then does a
77 single run through the entries. So if some entry matches more than
78 one parameter, it is printed using the first.
79 ·
80 absolute
81 All paths are printed in absolute form. This is useful if you want
82 to paste them into other consoles without worrying whether the
83 current directory matches.
84 The next two are nearly identical to absolute, but the beginning of
85 paths are substituted by environment variables. This makes sense if you
86 want the advantage of full paths, but have some of them abbreviated.
87 ·
88 environment
89 Match variables to directories after reading the known entries, and
90 use this cached information. This is faster, but might miss the best
91 case if new entries are found (which would not be checked against
92 possible longer hits).
93 Furthermore, as this works via associating environment variables to
94 entries, the environment variables must at least match the working
95 copy base - shorter paths won't be substituted.
96 · full-environment
97 Check for matches just before printing the path.
98 This is slower, but find the best fit.
99 Note:
100 The string of the environment variables must match a directory
101 name; the filename is always printed literally, and partial string
102 matches are not allowed. Feedback wanted.
103 Only environment variables whose names start with WC are used for
104 substitution, to avoid using variables like $PWD, $OLDPWD, $HOME
105 and similar which might differ between sessions. Maybe the allowed
106 prefixes for the environment variables should be settable in the
107 configuration. Opinions to the users mailing list, please.
108 Example, with / as working copy base:
109 $ cd /etc
110 $ fsvs -o path=wcroot st
112 $ fsvs -o path=absolute st
114 $ fsvs -o path=parameters st
116 $ fsvs -o path=parameters st .
117 $ fsvs -o path=parameters st /
118 $ fsvs -o path=parameters st X11
119 $ fsvs -o path=parameters st ../dev/..
120 $ fsvs -o path=parameters st X11 ../etc
121 $ fsvs -o path=parameters st ../etc X11
122 $ fsvs -o path=environ st
124 $ WCBAR=/etc fsvs -o path=wcroot st
125 $ WCBAR=/etc fsvs -o path=wcroot st /
126 $ WCBAR=/e fsvs -o path=wcroot st
127 $ WCBAR=/etc WCFOO=/etc/X11 fsvs -o path=wcroot st
128 $ touch /etc/X11/xinit/xinitrc
130 $ fsvs -o path=parameters st
131 $ fsvs -o path=parameters st X11 /etc/X11/xinit
132 Note:
134 At least for the command line options the strings can be
135 abbreviated, as long as they're still identifiable. Please use the
136 full strings in the configuration file, to avoid having problems in
137 future versions when more options are available.
139 The diff is not done internally in FSVS, but some other program is
140 called, to get the highest flexibility.
141 There are several option values:
142 · diff_prg: The executable name, default 'diff'.
143 · diff_opt: The default options, default '-pu'.
144 · diff_extra: Extra options, no default.
145 The call is done as
146 $diff_prg $diff_opt $file1 --label '$label1' $file2 --label '$label2' diff_extra
147 Note:
149 In diff_opt you should use only use command line flags without
150 parameters; in diff_extra you can encode a single flag with
151 parameter (like '-U5'). If you need more flexibility, write a shell
152 script and pass its name as diff_prg.
154 If you have colordiff installed on your system, you might be interested
155 in the colordiff option.
156 It can take on of these values:
157 · no, off or false: Don't use colordiff.
158 · yes, true or on: If this option is set on the commandline, or the
159 output is a tty, pipe the output of the diff program (see Options
160 relating to the 'diff' action) to colordiff.
161 · auto: Like yes, but don't throw an error if colordiff can't be
162 started; just pipe the data as-is to STDOUT.
163 The default value is auto.
165 Please see the command line parameter for -f, which is identical.
166 fsvs -o filter=mtime
168 Please see the command line parameter -W, which is identical.
169 fsvs -o warning=diff-status=ignore
171 This is a path that is prepended to $FSVS_WAA and $FSVS_CONF (or their
172 default values, see envs), if they do not already start with it, and it
173 is cut off for the directory-name MD5 calculation.
174 When is that needed? Imagine that you've booted from some Live-CD like
175 Knoppix; if you want to setup or restore a non-working system, you'd
176 have to transfer all files needed by the fsvs binary to it, and then
177 start in some kind of chroot environment.
178 With this parameter you can tell fsvs that it should load its libraries
179 from the current filesystem, but use the given path as root directory
180 for its administrative data.
181 This is used for recovery; see the example in Recovery for a non-
182 booting system.
183 So how does this work?
184 · The internal data paths derived from $FSVS_WAA and $FSVS_CONF use the
185 value given for softroot as a base directory, if they do not already
186 start with it. (If that creates a conflict for you, eg. in that you
187 want to use /var as the softroot, and your $FSVS_WAA should be
188 /var/fsvs, you can make the string comparison fail by using /./var
189 for either path.)
190 · When a directory name for $FSVS_CONF or $FSVS_WAA is derived from
191 some file path, the part matching softroot is cut off, so that the
192 generated names match the situation after rebooting.
193 Previously you'd have to export your data back to the filesystem and
194 call urls 'fsvs urls' and fsvs sync-repos again, to get the WAA data
195 back.
196 Note:
197 A plain chroot() would not work, as some needed programs (eg. the
198 decoder for update, see Special property names) would not be
199 available.
200 The easy way to understand softroot is: If you want to do a
201 chroot() into the given directory (or boot with it as /), you'll
202 want this set.
204 You can modify aspects of the fsvs log output format by setting the
205 log_output option to a combination of these flags:
206 · color: This uses color in the output, similar to cg-log (cogito-log);
207 the header and separator lines are highlighted.
208 Note:
209 This uses ANSI escape sequences, and tries to restore the default
210 color; if you know how to do that better (and more compatible),
211 please tell the developer mailing list.
212 · indent: Additionally you can shift the log message itself a space to
213 the right, to make the borders clearer.
214 Furthermore the value normal is available; this turns off all special
215 handling.
216 Note:
217 If you start such an option, the value is reseted; so if you
218 specify log_output=color,indent in the global config file, and use
219 log_output=color on the commandline, only colors are used. This is
220 a difference to the Filtering entries option, which is cumulating.
222 FSVS can colorize the output of the status lines; removed entries will
223 be printed in red, new ones in green, and otherwise changed in blue.
224 Unchanged (for -v) will be given in the default color.
225 For this you can set stat_color=yes; this is turned off per default.
226 As with the other colorizing options this gets turned off automatically
227 if the output is not on a tty; on the command line you can override
228 this, though.
230 If you'd like to have the output of status sorted, you can use the
231 option dir_sort=yes. FSVS will do a run through the tree, to read the
232 status of the entries, and then go through it again, but sorted by
233 name. (See dir_enumerator().)
234 Note:
235 If fsvs aborts with an error during status output, you might want
236 to turn this option off again (eg. on the commandline with
237 -odir_sort=no) to see where fsvs stops.
239 If you defined multiple URLs for your working copy, FSVS needs to know
240 which URL to commit to.
241 For this you would set commit_to to the name of the URL; see this
242 example:
243 fsvs urls N:master,P:10,http://... N:local,P:20,file:///...
244 fsvs ci /etc/passwd -m 'New user defined' -ocommit_to=local
245
247 See -d.
248 Example:
249 fsvs -o debug_output=/tmp/debug.out -d st /etc
250
252 In the default settings FSVS will happily create empty commits, ie.
253 revisions without any changed entry. These just have a revision number,
254 an author and a timestamp; this is nice if FSVS is run via CRON, and
255 you want to see when FSVS gets run.
256 If you would like to avoid such revisions, set this option to no; then
257 such commits will be avoided.
258 Example:
259 fsvs commit -o empty_commit=no -m 'cron' /etc
260 ef cpfd 'copyfrom-detect'
262 If you've got big files that are seen as new, doing the MD5 comparison
263 can be time consuming. So there's the option copyfrom_exp, which takes
264 the usual yes (default) and no arguments.
265 fsvs copyfrom-detect -o copyfrom_exp=no some_directory
267 If you're using fsvs in automated systems, you might see that changes
268 that happen in the same second as a commit are not seen with status
269 later; this is because the timestamp granularity of fsvs is 1 second.
270 For backward compatibility the default value is no (don't delay). You
271 can set it to any combination of
272 · commit,
274 · update,
275 · revert and/or
276 · checkout;
277 for yes all of these actions are delayed until the clock seconds
278 change.
279 Example how to set that option via an environment variable:
280 export FSVS_DELAY=commit,revert
281
283 If you start an update, but one of the entries that was changed in the
284 repository is changed locally too, you get a conflict.
285 There are some ways to resolve a conflict:
286 · local - Just take the local entry, ignore the repository.
288 · remote - Overwrite any local change with the remote version.
289 · both - Keep the local modifications in the file renamed to
290 filename.mine, and save the repository version as filename.rXXX, ie.
291 put the revision number after the filename.
292 These files will be seen as New; the conflict must be solved manually,
293 and the resolution made known to FSVS via resolve.
294 Note:
295 As there's no known good version after this renaming, a zero byte
296 file gets created.
297 Any resolve or revert command would make that current, and the
298 changes that are kept in filename.mine would be lost!
299 You could only revert to the last repository version, ie. the data
300 of filename.rXXX.
301 · merge - Call the program merge with the common ancestor, the local
302 and the remote version.
303 If it is a clean merge, no further work is necessary; else you'll get
304 the (partly) merged file, and the two other versions just like with the
305 both variant, and have to tell FSVS that the conflict is resolved by
306 resolve.
307 Note:
308 As in the subversion command line client svn the auxiliary files
309 are seen as new, although that might change in the future (so that
310 they automatically get ignored).
312 Like with diff, the merge operation is not done internally in FSVS.
313 To have better control
314 · merge_prg: The executable name, default 'merge'.
315 · merge_opt: The default options, default '-A'.
316 The option '-p' is always used:
317 $merge_prg $merge_opt -p $file1 $common $file2
318Version trunk:2078 1 Apr 2008 Further options for FSVS.(1)