libfossil
checkout.h
Go to the documentation of this file.
1/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* vim: set ts=2 et sw=2 tw=80: */
3#if !defined(ORG_FOSSIL_SCM_FSL_CHECKOUT_H_INCLUDED)
4#define ORG_FOSSIL_SCM_FSL_CHECKOUT_H_INCLUDED
5/*
6 Copyright 2013-2021 The Libfossil Authors, see LICENSES/BSD-2-Clause.txt
7
8 SPDX-License-Identifier: BSD-2-Clause-FreeBSD
9 SPDX-FileCopyrightText: 2021 The Libfossil Authors
10 SPDX-FileType: Code
11
12 Heavily indebted to the Fossil SCM project (https://fossil-scm.org).
13*/
14
15/** @file checkout.h
16
17 fossil-checkout.h declares APIs specifically dealing with
18 checkout-side state, as opposed to purely repository-db-side state
19 or non-content-related APIs.
20*/
21
22#include "db.h" /* MUST come first b/c of config macros */
23#include "repo.h"
24
25#if defined(__cplusplus)
26extern "C" {
27#endif
28
29
30/**
31 Tries to open a checked-out fossil repository db in the given
32 directory (or "." if dirName is NULL). This routine canonicalizes
33 its dirName argument using fsl_file_canonical_name(), then passes
34 that and checkParentDirs on to fsl_ckout_db_search() to find a
35 checkout db, so see that routine for how it searches.
36
37 If this routine finds/opens a checkout, it also tries to open
38 the repository database from which the checkout derives, and
39 fails if it cannot. The library never allows a checkout to be
40 opened without its corresponding repository partner because
41 a checkout has hard dependencies on the repo's state.
42
43 Returns 0 on success. If there is an error opening or validating
44 the checkout or its repository db, f's error state will be
45 updated. Error codes/conditions include:
46
47 - FSL_RC_MISUSE if f is NULL.
48
49 - FSL_RC_ACCESS if f already has and opened checkout.
50
51 - FSL_RC_OOM if an allocation fails.
52
53 - FSL_RC_NOT_FOUND if no checkout is foud or if a checkout's
54 repository is not found.
55
56 - FSL_RC_RANGE if dirname is not NULL but has a length of 0.
57
58 - Various codes from fsl_getcwd() (if dirName is NULL).
59
60 - Various codes if opening the associated repository DB fails.
61
62 TODO: there's really nothing in the architecture which restricts a
63 checkout db to being in the same directory as the checkout, except
64 for some historical bits which "could" be refactored. It "might be
65 interesting" to eventually provide a variant which opens a checkout
66 db file directly. We have the infrastructure, just need some
67 refactoring. It "shouldn't" require any trickery or
68 incompatibilities with fossil(1).
69*/
70FSL_EXPORT int fsl_ckout_open_dir( fsl_cx * const f, char const * dirName,
71 bool checkParentDirs );
72
73
74/**
75 Searches the given directory (or the current directory if dirName
76 is 0) for a fossil checkout database file named one of (_FOSSIL_,
77 .fslckout). If it finds one, it returns 0 and appends the file's
78 path to pOut if pOut is not 0. If neither is found AND if
79 checkParentDirs is true an then it moves up the path one directory
80 and tries again, until it hits the root of the dirPath (see below
81 for a note/caveat).
82
83 If dirName is NULL then it behaves as if it had been passed the
84 absolute path of the current directory (as determined by
85 fsl_getcwd()).
86
87 This function does no normalization of dirName. Because of that...
88
89 Achtung: if dirName is relative, this routine might not find a
90 checkout where it would find one if given an absolute path (because
91 it traverses the path string given it instead of its canonical
92 form). Whether this is a bug or a feature is not yet clear. When in
93 doubt, use fsl_file_canonical_name() to normalize the directory
94 name before passing it in here. If it turns out that we always want
95 that behaviour, this routine will be modified to canonicalize the
96 name.
97
98 This routine can return at least the following error codes:
99
100 - FSL_RC_NOT_FOUND: either no checkout db was found or the given
101 directory was not found.
102
103 - FSL_RC_RANGE if dirName is an empty string. (We could arguably
104 interpret this as a NULL string, i.e. the current directory.)
105
106 - FSL_RC_OOM if allocation of a filename buffer fails.
107
108 TODO?
109
110 - Why was the decision made not to canonicalize dirName from here?
111 We might want to change that.
112
113*/
114FSL_EXPORT int fsl_ckout_db_search( char const * dirName,
115 bool checkParentDirs,
116 fsl_buffer * const pOut );
117
118/**
119 Returns version information for the current checkout.
120
121 If f has an opened checkout then...
122
123 If uuid is not NULL then *uuid is set to the UUID of the opened
124 checkout, or NULL if there is no checkout. If rid is not NULL, *rid
125 is set to the record ID of that checkout, or 0 if there is no
126 checkout (or the current checkout is from an empty repository). The
127 returned uuid bytes and rid are owned by f and valid until the
128 library updates its checkout state to a newer checkout version
129 (essentially unpredictably). When in doubt about lifetime issues,
130 copy the UUID immediately after calling this if they will be needed
131 later.
132
133 Corner case: a new repo with no checkins has an RID of 0 and a UUID
134 of NULL. That does not happen with fossil-generated repositories,
135 as those always "seed" the database with an initial commit artifact
136 containing no files.
137*/
139 fsl_uuid_cstr * const uuid );
140
141/**
142 Given a fsl_cx with an opened checkout, and a file/directory name,
143 this function canonicalizes zOrigName to a form suitable for use as
144 an in-repo filename, _appending_ the results to pOut. If pOut is
145 NULL, it performs its normal checking but does not write a result,
146 other than to return 0 for success.
147
148 As a special case, if zOrigName refers to the top-level checkout
149 directory, it resolves to either "." or "./", depending on whether
150 zOrigName contains a trailing slash.
151
152 If relativeToCwd is true then the filename is canonicalized
153 based on the current working directory (see fsl_getcwd()),
154 otherwise f's current checkout directory is used as the virtual
155 root.
156
157 If the input name contains a trailing slash, it is retained in
158 the output sent to pOut except in the top-dir case mentioned
159 above.
160
161 Returns 0 on success, meaning that the value appended to pOut
162 (if not NULL) is a syntactically valid checkout-relative path.
163
164 Returns FSL_RC_RANGE if zOrigName points to a path outside
165 of f's current checkout root.
166
167 Returns FSL_RC_NOT_A_CKOUT if f has no checkout opened.
168
169 Returns FSL_RC_MISUSE if !zOrigName, FSL_RC_OOM on an allocation
170 error.
171
172 This function does not validate whether or not the file actually
173 exists, only that its name is potentially valid as a filename
174 for use in a checkout (though other, downstream rules might prohibit that, e.g.
175 the filename "..../...." is not valid but is not seen as invalid by
176 this function). (Reminder to self: we could run the end result through
177 fsl_is_simple_pathname() to catch that?)
178*/
179FSL_EXPORT int fsl_ckout_filename_check( fsl_cx * const f, bool relativeToCwd,
180 char const * zOrigName, fsl_buffer * const pOut );
181
182/**
183 Convenience typedef and required forward decl.
184 */
186
187/**
188 State passed to fsl_ckout_manage_f() callback.
189*/
191 /**
192 The fsl_cx instance for the correspnding fsl_ckout_manage()
193 call.
194 */
196 /**
197 The options object passed to the corresponding call to
198 fsl_ckout_manage(). This is provided primarily for access to
199 its callbackState member. The client must never modify any state
200 in this opt object other than the callbackState or to use other
201 APIs of this->f.
202 */
204 /**
205 The name of the file being managed, relative to the root of the
206 checkout. fsl_cx_stat2() can be used to transform it to an
207 absolute path, if needed. Given a fsl_ckout_manage_state
208 named `ms`, that call would look like:
209
210 ```
211 fsl_buffer_reuse(&yourBuffer);
212 // ^^^ noting that fsl_cx_stat2() APPENDS to the buffer.
213 int rc = fsl_cx_stat2(ms->f, false, ms->filename,
214 NULL, &yourBuffer, true);
215 // ^^^ noting that the stat "should not" fail in this case
216 // because fsl_ckout_manage() has validated that the file
217 // exists.
218 ```
219 */
220 char const * filename;
221};
222
223/**
224 Convenience typedef.
225*/
227
228/**
229 Callback type for use with fsl_ckout_manage_opt(). It should
230 inspect the given (`mst->filename`) using whatever criteria it likes, set
231 *include to true or false to indicate whether the filename is okay
232 to include the current add-file-to-repo operation, and return 0.
233
234 If it returns non-0 the add-file-to-repo process will end and that
235 error code will be reported to its caller. Such result codes must
236 come from the FSL_RC_xxx family. They may report details of
237 the error via fsl_cx_err_set() with the `mst->f` object.
238
239 It will be passed a name which is relative to the top-most checkout
240 directory.
241
242 The final argument is not used by the library, but is passed on
243 as-is from the fsl_ckout_manage_opt::callbackState pointer which
244 is passed to fsl_ckout_manage().
245*/
247 bool *include);
248/**
249 Options for use with fsl_ckout_manage().
250*/
252 /**
253 The file or directory name to add. If it is a directory, the add
254 process will recurse into it.
255
256 Note that filenames need to be passed in their "proper" case for
257 the current platform. fsl_filename_preferred_case() case be used
258 to do that, but that functionality is not currently part of the
259 fsl_ckout_manage() inner workings (that may change at some
260 point). fsl_cx_is_case_sensitive() can be used to determine
261 whether or not case-sensitivity is preferred for the current
262 repository.
263 */
264 char const * filename;
265 /**
266 Whether to evaluate the given name as relative to the current working
267 directory or to the current checkout root.
268
269 This makes a subtle yet important difference in how the name is
270 resolved. CLI apps which take file names from the user from
271 within a checkout directory will generally want to set
272 relativeToCwd to true. GUI apps, OTOH, will possibly need it to
273 be false, depending on how they resolve and pass on the
274 filenames.
275 */
277 /**
278 Whether or not to check the name(s) against the 'ignore-globs'
279 config setting (if set).
280 */
282 /**
283 Optional predicate function which may be called for each
284 to-be-added filename. It is only called if:
285
286 - It is not NULL (obviously) and...
287
288 - The file is not already in the checkout database and...
289
290 - The is-internal-name check passes (see
291 fsl_reserved_fn_check()) and...
292
293 - If checkIgnoreGlobs is false or the name does not match one of
294 the ignore-globs values.
295
296 The name it is passed is relative to the checkout root.
297
298 Because the callback is called only if other options have not
299 already excluded the file, the client may use the callback to
300 report to the user (or otherwise record) exactly which files
301 get added.
302 */
304
305 /**
306 State to be passed to this->callback.
307 */
309
310 /**
311 These counts are updated by fsl_ckout_manage() to report
312 what it did.
313 */
314 struct {
315 /**
316 Number of files actually added by fsl_ckout_manage().
317 */
318 uint32_t added;
319 /**
320 Number of files which were requested to be added but were only
321 updated because they had previously been added. Updates set the
322 vfile table entry's current mtime, executable-bit state, and
323 is-it-a-symlink state. (That said, this code currently ignores
324 symlinks altogether!)
325 */
326 uint32_t updated;
327 /**
328 The number of files skipped over for addition. This includes
329 files which meet any of these criteria:
330
331 - fsl_reserved_fn_check() fails.
332
333 - If the checkIgnoreGlobs option is true and a filename matches
334 any of those globs.
335
336 - The client-provided callback says not to include the file.
337 */
338 uint32_t skipped;
340};
341/**
342 Initialized-with-defaults fsl_ckout_manage_opt instance,
343 intended for use in const-copy initialization.
344*/
345#define fsl_ckout_manage_opt_empty_m {\
346 NULL/*filename*/, true/*relativeToCwd*/, true/*checkIgnoreGlobs*/, \
347 NULL/*callback*/, NULL/*callbackState*/, \
348 {/*counts*/ 0/*added*/, 0/*updated*/, 0/*skipped*/} \
349 }
350/**
351 Initialized-with-defaults fsl_ckout_manage_opt instance,
352 intended for use in non-const copy initialization.
353*/
355
356/**
357 Adds the given filename or directory (recursively) to the current
358 checkout vfile list of files as a to-be-added file, or updates an
359 existing record if one exists.
360
361 This function ensures that opt->filename gets canonicalized and can
362 be found under the checkout directory, and fails if no such file
363 exists (checking against the canonicalized name). Filenames are all
364 filtered through fsl_reserved_fn_check() and may have other filters
365 applied to them, as determined by the options object.
366
367 Each filename which passes through the filters is passed to
368 the opt->callback (if not NULL), which may perform a final
369 filtering check and/or alert the client about the file being
370 queued.
371
372 The options object is non-const because this routine updates
373 opt->counts when it adds, updates, or skips a file. On each call,
374 it updated opt->counts without resetting it (as this function is
375 typically called in a loop). This function does not modify any
376 other entries of that object and it requires that the object not be
377 modified (e.g. via opt->callback()) while it is recursively
378 processing. To reset the counts between calls, if needed:
379
380 ```
381 opt->counts = fsl_ckout_manage_opt_empty.counts;
382 ```
383
384 Returns 0 on success, non-0 on error.
385
386 Files queued for addition this way can be unqueued before they are
387 committed using fsl_ckout_unmanage().
388
389 To avoid Significant Grief, this routine automatically skips any
390 directories under opt->filename which appear to be fossil checkout
391 roots unless that directory is f's current checkout directory, into
392 which it will recurse normally.
393
394 @see fsl_ckout_unmanage()
395 @see fsl_reserved_fn_check()
396*/
398 fsl_ckout_manage_opt * const opt );
399
400/**
401 Convenience typedef and required forward decl.
402 */
404
405/**
406 State passed to fsl_ckout_unmanage_f() callback.
407*/
409 /**
410 The fsl_cx instance for the correspnding fsl_ckout_unmanage()
411 call.
412 */
414 /**
415 The options object passed to the corresponding call to
416 fsl_ckout_unmanage(). This is provided primarily for access to
417 its callbackState member. The client must never modify any state
418 in this opt object other than the callbackState or to use other
419 APIs of this->f.
420 */
422 /**
423 The name of the file being unmanaged, relative to the root of the
424 checkout. fsl_cx_stat2() can be used to transform it to an
425 absolute path, if needed. Given a fsl_ckout_unmanage_state
426 named `ums`, that call would look like:
427
428 ```
429 fsl_buffer_reuse(&yourBuffer);
430 // ^^^ noting that fsl_cx_stat2() APPENDS to the buffer.
431 int rc = fsl_cx_stat2(ums->f, false, ums->filename,
432 NULL, &yourBuffer, true);
433 // ^^^ noting that the stat will legitimately and harmlessly
434 // fail if the file does not exist, so this error can
435 // normally be ignored.
436 ```
437 */
438 char const * filename;
439};
440
441/** Convenience typedef. */
443
444
445/**
446 Callback type for use with fsl_ckout_unmanage(). It is called
447 by the removal process, immediately after a file is "removed"
448 from SCM management (a.k.a. when the file becomes "unmanaged").
449
450 If it returns non-0 the unmanage process will end and that error
451 code will be reported to its caller. Such result codes must come
452 from the FSL_RC_xxx family. They may report details of the error
453 via fsl_cx_err_set() with the `ums->f` object.
454
455 The object passed to it will hold the name of the file being
456 unmanaged, relative to the top-most checkout directory. The client
457 is free to unlink the file from the filesystem if they like - the
458 library does not do so automatically
459*/
461
462/**
463 Options for use with fsl_ckout_unmanage().
464*/
466 /**
467 The file or directory name to add. If it is a directory, the add
468 process will recurse into it. See also this->vfileIds.
469 */
470 char const * filename;
471 /**
472 An alternative to assigning this->filename is to point
473 this->vfileIds to a bag of vfile.id values. If this member is not
474 NULL, fsl_ckout_unmanage() will ignore this->filename.
475
476 @see fsl_filename_to_vfile_ids()
477 */
479 /**
480 Whether to evaluate this->filename as relative to the current
481 working directory (true) or to the current checkout root
482 (false). This is ignored when this->vfileIds is not NULL.
483
484 This makes a subtle yet important difference in how the name is
485 resolved. CLI apps which take file names from the user from
486 within a checkout directory will generally want to set
487 relativeToCwd to true. GUI apps, OTOH, will possibly need it to
488 be false, depending on how they resolve and pass on the
489 filenames.
490 */
492 /**
493 If true, fsl_vfile_changes_scan() is called to ensure that
494 the filesystem and vfile tables agree. If the client code has
495 called that function, or its equivalent, since any changes were
496 made to the checkout then this may be set to false to speed up
497 the rm process.
498 */
500 /**
501 Optional predicate function which will be called after each
502 file is made unmanaged.
503
504 The name it is passed is relative to the checkout root.
505 */
507 /**
508 State to be passed to this->callback.
509 */
511};
512/**
513 Initialized-with-defaults fsl_ckout_unmanage_opt instance,
514 intended for use in const-copy initialization.
515*/
516#define fsl_ckout_unmanage_opt_empty_m {\
517 NULL/*filename*/, NULL/*vfileIds*/,\
518 true/*relativeToCwd*/,true/*scanForChanges*/, \
519 NULL/*callback*/, NULL/*callbackState*/ \
520}
521/**
522 Initialized-with-defaults fsl_ckout_unmanage_opt instance,
523 intended for use in non-const copy initialization.
524*/
526
527/**
528 The converse of fsl_ckout_manage(), this queues a file for removal
529 from the current checkout. Unlike fsl_ckout_manage(), this routine
530 does not ensure that opt->filename actually exists - it only
531 normalizes zFilename into its repository-friendly form and passes
532 it through the vfile table.
533
534 If opt->filename refers to a directory then this operation queues
535 all files under that directory (recursively) for removal. In this
536 case, it is irrelevant whether or not opt->filename ends in a
537 trailing slash.
538
539 Returns 0 on success, any of a number of non-0 codes on error.
540 Returns FSL_RC_MISUSE if !opt->filename or !*opt->filename.
541 Returns FSL_RC_NOT_A_CKOUT if f has no opened checkout.
542
543 If opt->callback is not NULL, it is called for each
544 newly-unamanaged entry. The intention is to provide it the
545 opportunity to notify the user, record the filename for later use,
546 remove the file from the filesystem, etc. If it returns non-0, the
547 unmanaging process will fail with that code and any pending
548 transaction will be placed into a rollback state.
549
550 This routine does not actually remove any files from the
551 filesystem, it only modifies the vfile table entry so that the
552 file(s) will be removed from the SCM by the commit process. If
553 opt->filename is an entry which was previously
554 fsl_ckout_manage()'d, but not yet committed, or any such entries
555 are found under directory opt->filename, they are removed from the
556 vfile table. i.e. this effective undoes the add operation.
557
558 @see fsl_ckout_manage()
559*/
561 fsl_ckout_unmanage_opt const * opt );
562
563/**
564 Hard-coded range of values of the vfile.chnged db field.
565 These values are part of the fossil schema and must not
566 be modified.
567*/
569 /** File is unchanged. */
571 /** File edit. */
573 /** File changed due to a merge. */
575 /** File added by a merge. */
577 /** File changed due to an integrate merge. */
579 /** File added by an integrate merge. */
581 /** File became executable but has unmodified contents. */
583 /** File became a symlink whose target equals its old contents. */
585 /** File lost executable status but has unmodified contents. */
587 /** File lost symlink status and has contents equal to its old target. */
589};
591
592/**
593 Change-type flags for use with fsl_ckout_changes_visit() and
594 friends.
595
596 TODO: consolidate this with fsl_vfile_change_e insofar as possible.
597 There are a few checkout change statuses not reflected in
598 fsl_vfile_change_e.
599*/
601/**
602 Sentinel placeholder value.
603*/
605/**
606 Indicates that a file was modified in some unspecified way.
607*/
609/**
610 Indicates that a file was modified as the result of a merge.
611*/
613/**
614 Indicates that a file was added as the result of a merge.
615*/
617/**
618 Indicates that a file was modified as the result of an
619 integrate-merge.
620*/
622/**
623 Indicates that a file was added as the result of an
624 integrate-merge.
625*/
627/**
628 Indicates that the file gained the is-executable trait
629 but is otherwise unmodified.
630*/
632/**
633 Indicates that the file has changed to a symlink.
634*/
636/**
637 Indicates that the file lost the is-executable trait
638 but is otherwise unmodified.
639*/
641/**
642 Indicates that the file was previously a symlink but is
643 now a plain file.
644*/
646/**
647 Indicates that a file was added.
648*/
650/**
651 Indicates that a file was removed from SCM management.
652*/
654/**
655 Indicates that a file is missing from the local checkout.
656*/
658/**
659 Indicates that a file was renamed.
660*/
662};
663
665
666/**
667 This is equivalent to calling fsl_vfile_changes_scan() with the
668 arguments (f, -1, 0).
669
670 @see fsl_ckout_changes_visit()
671 @see fsl_vfile_changes_scan()
672*/
674
675/**
676 A typedef for visitors of checkout status information via
677 fsl_ckout_changes_visit(). Implementions will receive the
678 last argument passed to fsl_ckout_changes_visit() as their
679 first argument. The second argument indicates the type of change
680 and the third holds the repository-relative name of the file.
681
682 If changes is FSL_CKOUT_CHANGE_RENAMED then origName will hold
683 the original name, else it will be NULL.
684
685 Implementations must return 0 on success, non-zero on error. On
686 error any looping performed by fsl_ckout_changes_visit() will
687 stop and this function's result code will be returned.
688
689 @see fsl_ckout_changes_visit()
690*/
691typedef int (*fsl_ckout_changes_f)(void * state, fsl_ckout_change_e change,
692 char const * filename,
693 char const * origName);
694
695/**
696 Compares the changes of f's local checkout against repository
697 version vid (checkout version if vid is negative). For each
698 change detected it calls visitor(state,...) to report the
699 change. If visitor() returns non-0, that code is returned from
700 this function. If doChangeScan is true then
701 fsl_ckout_changes_scan() is called by this function before
702 iterating, otherwise it is assumed that the caller has called
703 that or has otherwise ensured that the checkout db's vfile table
704 has been populated.
705
706 If the callback returns FSL_RC_BREAK, this function stops iteration
707 and returns 0.
708
709 Returns 0 on success.
710
711 @see fsl_ckout_changes_scan()
712*/
714 bool doChangeScan,
715 fsl_ckout_changes_f visitor,
716 void * state );
717/**
718 A bitmask of flags for fsl_vfile_changes_scan().
719*/
721/**
722 The empty flags set.
723*/
725
726/**
727 Non-file/non-link FS objects trigger an error.
728*/
730/**
731 Verify file content using hashing, regardless of whether or not
732 file timestamps differ.
733*/
735/**
736 For unchanged or changed-by-merge files, set the mtime to last
737 check-out time, as determined by fsl_mtime_of_manifest_file().
738*/
740/**
741 Indicates that when populating the vfile table, it should be not be
742 cleared of entries for other checkins. Normally we want to clear
743 all versions except for the one we're working with, but at least
744 a couple of use cases call for having multiple versions in vfile at
745 once. Many algorithms generally assume only a single checkin's
746 worth of state is in vfile and can get confused if that is not the
747 case.
748*/
750/**
751 If set and fsl_vfile_changes_scan() is passed a version other than
752 the pre-call checkout version, it will, when finished, write the
753 given version in the "checkout" setting of the ckout.vvar table,
754 effectively switching the checkout to that version. It does not do
755 this by default because it is sometimes necessary to have two
756 versions in the vfile table at once and the operation doing so
757 needs to control which version number is the current checkout.
758*/
760};
761
762/**
763 This function populates (if needed) the vfile table of f's
764 checkout db for the given checkin version ID then compares files
765 listed in it against files in the checkout directory, updating
766 vfile's status for the current checkout version id as its goes. If
767 vid is<=0 then the current checkout's RID is used in its place
768 (note that 0 is the RID of an initial empty repository!).
769
770 cksigFlags must be 0 or a bitmask of fsl_ckout_sig_e values.
771
772 This is a relatively memory- and filesystem-intensive operation,
773 and should not be performed more often than necessary. Many SCM
774 algorithms rely on its state being correct, however, so it's
775 generally better to err on the side of running it once too often
776 rather than once too few times.
777
778 Returns 0 on success, non-0 on error.
779
780 BUG: this does not properly catch one particular corner-case
781 change, where a file has been replaced by a same-named non-file
782 (symlink or directory).
783*/
785 unsigned cksigFlags);
786
787/**
788 If f has an opened checkout which has local changes noted in its
789 checkout db state (the vfile table), returns true, else returns
790 false. Note that this function does not do the filesystem scan to
791 check for changes, but checks only the db state. Use
792 fsl_vfile_changes_scan() to perform the actual scan (noting that
793 library-side APIs which update that state may also record
794 individual changes or automatically run a scan).
795*/
797
798/**
799 Callback type for use with fsl_checkin_queue_opt for alerting a
800 client about exactly which files get enqueued/dequeued via
801 fsl_checkin_enqueue() and fsl_checkin_dequeue().
802
803 This function gets passed the checkout-relative name of the file
804 being enqueued/dequeued and the client-provided state pointer which
805 was passed to the relevant API. It must return 0 on success. If it
806 returns non-0, the API on whose behalf this callback is invoked
807 will propagate that error code back to the caller.
808
809 The intent of this callback is simply to report changes to the
810 client, not to perform validation. Thus such callbacks "really
811 should not fail" unless, e.g., they encounter an OOM condition or
812 some such. Any validation required by the client should be
813 performed before calling fsl_checkin_enqueue()
814 resp. fsl_checkin_dequeue().
815*/
816typedef int (*fsl_checkin_queue_f)(const char * filename, void * state);
817
818/**
819 Options object type used by fsl_checkin_enqueue() and
820 fsl_checkin_dequeue().
821*/
823 /**
824 File or directory name to enqueue/dequeue to/from a pending
825 checkin.
826 */
827 char const * filename;
828 /**
829 If true, filename (if not absolute) is interpreted as relative to
830 the current working directory, else it is assumed to be relative
831 to the top of the current checkout directory.
832 */
834
835 /**
836 If not NULL then this->filename and this->relativeToCwd are
837 IGNORED and any to-queue filename(s) is/are added from this
838 container. It is an error (FSL_RC_MISUSE) to pass an empty bag.
839 (Should that be FSL_RC_RANGE instead?)
840
841 The bag is assumed to contain values from the vfile.id checkout
842 db field, refering to one or more files which should be queued
843 for the pending checkin. It is okay to pass IDs for unmodified
844 files or to queue the same files multiple times. Unmodified files
845 may be enqueued but will be ignored by the checkin process if, at
846 the time the checkin is processed, they are still unmodified.
847 Duplicated entries are simply ignored for the 2nd and subsequent
848 inclusion.
849
850 @see fsl_ckout_vfile_ids()
851 */
853
854 /**
855 If true, fsl_vfile_changes_scan() is called to ensure that the
856 filesystem and vfile tables agree. If the client code has called
857 that function, or its equivalent, since any changes were made to
858 the checkout then this may be set to false to speed up the
859 enqueue process. This is only used by fsl_checkin_enqueue(), not
860 fsl_checkin_dequeue().
861 */
863
864 /**
865 If true, only flagged-as-modified files will be enqueued by
866 fsl_checkin_enqueue(). By and large, this should be set to
867 true. Setting this to false is generally only intended/useful for
868 testing.
869 */
871
872 /**
873 It not NULL, is pass passed the checkout-relative filename of
874 each enqueued/dequeued file and this->callbackState. See the
875 callback type's docs for more details.
876 */
878
879 /**
880 Opaque client-side state for use as the 2nd argument to
881 this->callback.
882 */
884
885 /* TODO (2023-02-02): any state necessary for indicating that this
886 checking should be flagged as "private".
887 */
888};
889
890/** Convenience typedef. */
892
893/** Initialized-with-defaults fsl_checkin_queue_opt structure, intended for
894 const-copy initialization. */
895#define fsl_checkin_queue_opt_empty_m { \
896 NULL/*filename*/,true/*relativeToCwd*/, \
897 NULL/*vfileIds*/, \
898 true/*scanForChanges*/,true/*onlyModifiedFiles*/, \
899 NULL/*callback*/,NULL/*callbackState*/ \
900}
901
902/** Initialized-with-defaults fsl_checkin_queue_opt structure, intended for
903 non-const copy initialization. */
905
906/**
907 Adds one or more files to f's list of "selected" files - those
908 which should be included in the next commit (see
909 fsl_checkin_commit()).
910
911 Warning: if this function is not called before
912 fsl_checkin_commit(), then fsl_checkin_commit() will select all
913 modified, fsl_ckout_manage()'d, fsl_ckout_unmanage()'d, or renamed
914 files by default.
915
916 opt->filename must be a non-empty NUL-terminated string. The
917 filename is canonicalized via fsl_ckout_filename_check() - see that
918 function for the meaning of the opt->relativeToCwd parameter. To
919 queue all modified files in a checkout, set opt->filename to ".",
920 opt->relativeToCwd to false, and opt->onlyModifiedFiles to true.
921 "Modified" includes any which are pending deletion, are
922 newly-added, or for which a rename is pending.
923
924 The resolved name must refer to either a single vfile.pathname
925 value in the current vfile table or to a checkout-root-relative
926 directory. All matching filenames which refer to modified files (as
927 recorded in the vfile table) are queued up for the next commit.
928 If opt->filename is NULL, empty, or ("." and opt->relativeToCwd is false)
929 then all files in the vfile table are checked for changes.
930
931 If opt->scanForChanges is true then fsl_vfile_changes_scan() is
932 called before starting to ensure that the vfile entries are up to
933 date. If the client app has "recently" run that (or its
934 equivalent), that (slow) step can be skipped by setting
935 opt->scanForChanges to false before calling this
936
937 Note that after this returns, any given file may still be modified
938 by the client before the commit takes place, and the changes on
939 disk at the point of the fsl_checkin_commit() are the ones which
940 get saved (or not).
941
942 For each resolved entry which actually gets enqueued (i.e. was not
943 already enqueued and which is marked as modified), opt->callback
944 (if it is not NULL) is passed the checkout-relative file name and
945 the opt->callbackState pointer.
946
947 Returns 0 on success, FSL_RC_MISUSE if either pointer is NULL, or
948 *zName is NUL. Returns FSL_RC_OOM on allocation error. It is not
949 inherently an error for opt->filename to resolve to no queue-able
950 entries. A client can check for that case, if needed, by assigning
951 opt->callback and incrementing a counter in that callback. If the
952 callback is never called, no queue-able entries were found.
953
954 On error f's error state might (depending on the nature of the
955 problem) contain more details.
956
957 @see fsl_checkin_is_enqueued()
958 @see fsl_checkin_dequeue()
959 @see fsl_checkin_discard()
960 @see fsl_checkin_commit()
961*/
963 fsl_checkin_queue_opt const * opt);
964
965/**
966 The opposite of fsl_checkin_enqueue(), this opt->filename,
967 which may resolve to a single name or a directory, from the checkin
968 queue. Returns 0 on succes. This function does no validation on
969 whether a given file(s) actually exist(s), it simply asks the
970 internals to clean up matching strings from the checkout's vfile
971 table. Specifically, it does not return an error if this operation
972 finds no entries to dequeue.
973
974 If opt->filename is empty or NULL then ALL files are unqueued from
975 the pending checkin.
976
977 If opt->relativeToCwd is true (non-0) then opt->filename is
978 resolved based on the current directory, otherwise it is resolved
979 based on the checkout's root directory.
980
981 If opt->filename is not NULL or empty, this functions runs the
982 given path through fsl_ckout_filename_check() and will fail if that
983 function fails, propagating any error from that function. Ergo,
984 opt->filename must refer to a path within the current checkout.
985
986 @see fsl_checkin_enqueue()
987 @see fsl_checkin_is_enqueued()
988 @see fsl_checkin_discard()
989 @see fsl_checkin_commit()
990*/
992 fsl_checkin_queue_opt const * opt);
993
994/**
995 Returns true if the file named by zName is in f's current file
996 checkin queue. If NO files are in the current selection queue then
997 this routine assumes that ALL files are implicitely selected. As
998 long as at least one file is enqueued (via fsl_checkin_enqueue())
999 then this function only returns true for files which have been
1000 explicitly enqueued.
1001
1002 If relativeToCwd then zName is resolved based on the current
1003 directory, otherwise it assumed to be related to the checkout's
1004 root directory.
1005
1006 This function returning true does not necessarily indicate that
1007 the file _will_ be checked in at the next commit. If the file has
1008 not been modified at commit-time then it will not be part of the
1009 commit.
1010
1011 This function honors the fsl_cx_is_case_sensitive() setting
1012 when comparing names.
1013
1014 Achtung: this does not resolve directory names like
1015 fsl_checkin_enqueue() and fsl_checkin_dequeue() do. It
1016 only works with file names.
1017
1018 Results are undefined if f is NULL.
1019
1020 @see fsl_checkin_enqueue()
1021 @see fsl_checkin_dequeue()
1022 @see fsl_checkin_discard()
1023 @see fsl_checkin_commit()
1024*/
1026 char const * zName,
1027 bool relativeToCwd);
1028
1029/**
1030 Discards any state accumulated for a pending checking,
1031 including any files queued via fsl_checkin_enqueue()
1032 and tags added via fsl_checkin_T_add().
1033
1034 @see fsl_checkin_enqueue()
1035 @see fsl_checkin_dequeue()
1036 @see fsl_checkin_is_enqueued()
1037 @see fsl_checkin_commit()
1038 @see fsl_checkin_T_add()
1039*/
1041
1042/**
1043 Parameters for fsl_checkin_commit().
1044
1045 Checkins are created in a multi-step process:
1046
1047 - fsl_checkin_enqueue() queues up a file or directory for
1048 commit at the next commit.
1049
1050 - fsl_checkin_dequeue() removes an entry, allowing
1051 UIs to toggle files in and out of a checkin before
1052 committing it.
1053
1054 - fsl_checkin_is_enqueued() can be used to determine whether
1055 a given name is already enqueued or not.
1056
1057 - fsl_checkin_T_add() can be used to T-cards (tags) to a
1058 deck. Branch tags are intended to be applied via the
1059 fsl_checkin_opt::branch member.
1060
1061 - fsl_checkin_discard() can be used to cancel any pending file
1062 enqueuings, effectively cancelling a commit (which can be
1063 re-started by enqueuing another file).
1064
1065 - fsl_checkin_commit() creates a checkin for the list of enqueued
1066 files (defaulting to all modified files in the checkout!). It
1067 takes an object of this type to specify a variety of parameters
1068 for the check.
1069
1070 Note that this API uses the terms "enqueue" and "unqueue" rather
1071 than "add" and "remove" because those both have very specific
1072 (and much different) meanings in the overall SCM scheme.
1073*/
1075 /**
1076 The commit message. May not be empty - the library
1077 forbids empty checkin messages.
1078 */
1079 char const * message;
1080
1081 /**
1082 The optional mime type for the message. Only set
1083 this if you know what you're doing.
1084 */
1085 char const * messageMimeType;
1086
1087 /**
1088 The user name for the checkin. If NULL or empty, it defaults to
1089 fsl_cx_user_get(). If that is NULL, a FSL_RC_RANGE error is
1090 triggered.
1091 */
1092 char const * user;
1093
1094 /**
1095 If not NULL, makes the checkin the start of a new branch with
1096 this name.
1097 */
1098 char const * branch;
1099
1100 /**
1101 If this->branch is not NULL, this is applied as its "bgcolor"
1102 propagating property. If this->branch is NULL then this is
1103 applied as a one-time color tag to the checkin.
1104
1105 It must be NULL, empty, or in a form usable by HTML/CSS,
1106 preferably \#RRGGBB form. Length-0 values are ignored (as if
1107 they were NULL).
1108 */
1109 char const * bgColor;
1110
1111 /**
1112 If true, the checkin will be marked as private, otherwise it
1113 will be marked as private or public, depending on whether or
1114 not it inherits private content.
1115 */
1117
1118 /**
1119 Whether or not to calculate an R-card. Doing so is very
1120 expensive (memory and I/O) but it adds another layer of
1121 consistency checking to manifest files. In practice, the R-card
1122 is somewhat superfluous and the cost of calculating it has
1123 proven painful on very large repositories. fossil(1) creates an
1124 R-card for all checkins but does not require that one be set
1125 when it reads a manifest.
1126 */
1128
1129 /**
1130 Tells the checkin to close merged-in branches (merge type of
1131 0). INTEGRATE merges (type=-4) are always closed by a
1132 checkin. This does not apply to CHERRYPICK (type=-1) and
1133 BACKOUT (type=-2) merges.
1134 */
1136
1137 /**
1138 If true, allow a file to be checked in if it contains
1139 fossil-style merge conflict markers, else fail if an attempt is
1140 made to commit any files with such markers.
1141 */
1143
1144 /**
1145 A hint to fsl_checkin_commit() about whether it needs to scan the
1146 checkout for changes. Set this to false ONLY if the calling code
1147 calls fsl_ckout_changes_scan() (or equivalent,
1148 e.g. fsl_vfile_changes_scan()) immediately before calling
1149 fsl_checkin_commit(). fsl_checkin_commit() requires a non-stale
1150 changes scan in order to function properly, but it's a
1151 computationally slow operation so the checkin process does not
1152 want to duplicate it if the application has recently done so.
1153 */
1155
1156 /**
1157 NOT YET IMPLEMENTED! TODO!
1158
1159 If true, files which are removed from the SCM by this checkin
1160 should be removed from the filesystem.
1161
1162 Reminder to self: when we do this, incorporate
1163 fsl_rm_empty_dirs().
1164 */
1166
1167 /**
1168 If true, the checkin's db savepoint is rolled back after it's
1169 complete, effectively meaning that the checkin does not take
1170 place (but all of the work involved happens). This unfortunately
1171 has to put any pending transactions into pending-rollback mode,
1172 too, because of $REASONS.
1173 */
1175
1176 /**
1177 Whether to allow (or try to force) a delta manifest or not. 0
1178 means no deltas allowed - it will generate a baseline
1179 manifest. Greater than 0 forces generation of a delta if
1180 possible (if one can be readily found) even if doing so would not
1181 save a notable amount of space. Less than 0 means to
1182 decide via some heuristics.
1183
1184 A "readily available" baseline means either the current checkout
1185 is a baseline or has a baseline. In either case, we can use that
1186 as a baseline for a delta. i.e. a baseline "should" generally be
1187 available except on the initial checkin, which has neither a
1188 parent checkin nor a baseline.
1189
1190 The current behaviour for "auto-detect" mode is: it will generate
1191 a delta if a baseline is "readily available" _and_ the repository
1192 has at least one delta already. Once it calculates a delta form,
1193 it calculates whether that form saves any appreciable
1194 space/overhead compared to whether a baseline manifest was
1195 generated. If so, it discards the delta and re-generates the
1196 manifest as a baseline. The "force" behaviour (deltaPolicy>0)
1197 bypasses the "is it too big?" test, and is only intended for
1198 testing, not real-life use.
1199
1200 Caveat: if the repository has the "forbid-delta-manifests" set to
1201 a true value, this option is ignored: that setting takes
1202 priority. Similarly, it will not create a delta in a repository
1203 unless a delta has been "seen" in that repository before or this
1204 policy is set to >0. When a checkin is created with a delta
1205 manifest, that fact gets recorded in the repository's config
1206 table.
1207
1208 Note that delta manifests have some advantages and may not
1209 actually save much (if any) repository space because the
1210 lower-level delta framework already compresses parent versions of
1211 artifacts tightly. For more information see:
1212
1213 https://fossil-scm.org/home/doc/tip/www/delta-manifests.md
1214 */
1216
1217 /**
1218 Time of the checkin. If 0 or less, the time of the
1219 fsl_checkin_commit() call is used.
1220 */
1222
1223 /**
1224 If this is not NULL then the committed manifest will include a
1225 tag which closes the branch. The value of this string will be
1226 the value of the "closed" tag, and the value may be an empty
1227 string. The intention is that this gets set to a comment about
1228 why the branch is closed, but it is in no way mandatory.
1229 */
1230 char const * closeBranch;
1231
1232 /**
1233 Tells fsl_checkin_commit() to dump the generated manifest to
1234 this file. Intended only for debugging and testing. Checking in
1235 will fail if this file cannot be opened for writing.
1236 */
1237 char const * dumpManifestFile;
1238 /*
1239 fossil(1) has many more options. We might want to wrap some of
1240 it up in the "incremental" state (f->ckin.mf).
1241
1242 TODOs:
1243
1244 A callback mechanism which supports the user cancelling
1245 the checkin. It is (potentially) needed for ops like
1246 confirming the commit of CRNL-only changes.
1247
1248 2021-03-09: we now have fsl_confirmer for this but currently no
1249 part of the checkin code needs a prompt.
1250 */
1251};
1252
1253/**
1254 Empty-initialized fsl_checkin_opt instance, intended for use in
1255 const-copy constructing.
1256*/
1257#define fsl_checkin_opt_empty_m { \
1258 .message = NULL, \
1259 .messageMimeType = NULL, \
1260 .user = NULL, \
1261 .branch = NULL, \
1262 .bgColor = NULL, \
1263 .isPrivate = false, \
1264 .calcRCard = true, \
1265 .integrate = false, \
1266 .allowMergeConflict = false,\
1267 .scanForChanges = true,\
1268 .rmRemovedFiles = false,\
1269 .dryRun = false, \
1270 .deltaPolicy = 0, \
1271 .julianTime = 0.0, \
1272 .closeBranch = NULL, \
1273 .dumpManifestFile = NULL \
1274}
1275
1276/**
1277 Empty-initialized fsl_checkin_opt instance, intended for use in
1278 copy-constructing. It is important that clients copy this value
1279 (or fsl_checkin_opt_empty_m) to cleanly initialize their
1280 fsl_checkin_opt instances, as this may set default values which
1281 (e.g.) a memset() would not.
1282*/
1284
1285/**
1286 This creates and saves a "checkin manifest" for the current
1287 checkout.
1288
1289 Its primary inputs is a list of files to commit. This list is
1290 provided by the client by calling fsl_checkin_enqueue() one or
1291 more times. If no files are explicitely selected (enqueued) then
1292 it calculates which local files have changed vs the current
1293 checkout and selects all of those.
1294
1295 Non-file inputs are provided via the opt parameter.
1296
1297 On success, it returns 0 and...
1298
1299 - If newRid is not NULL, it is assigned the new checkin's RID
1300 value.
1301
1302 - If newUuid is not NULL, it is assigned the new checkin's UUID
1303 value. Ownership of the bytes is passed to the caller, who must
1304 eventually pass them to fsl_free() to free them.
1305
1306 Note that the new RID and UUID can also be fetched afterwards by
1307 calling fsl_ckout_version_info().
1308
1309 On error non-0 is returned and f's error state may (depending on
1310 the nature of the problem) contain details about the problem.
1311 Note, however, that any error codes returned here may have arrived
1312 from several layers down in the internals, and may not have a
1313 single specific interpretation here. When possible/practical, f's
1314 error state gets updated with a human-readable description of the
1315 problem.
1316
1317 opt->dryRun: does not work properly, at least partially due to
1318 stale internal caches.
1319
1320 ACHTUNG: all pending checkin state is cleared by this function
1321 unless it fails basic argument validation. This means any queued
1322 files or tags need to be re-applied if the client wants to try
1323 again. That is somewhat of a bummer, but this behaviour is the only
1324 way we can ensure that then the pending checkin state does not get
1325 garbled on a second use. When in doubt about the state, the client
1326 should call fsl_checkin_discard() to clear it before try to
1327 re-commit. (Potential TODO: add a success/fail state flag to the
1328 checkin state and only clean up on success? OTOH, since something
1329 in the state likely caused the problem, we might not want to do
1330 that.)
1331
1332 Some of the more notable, potentially not obvious, error
1333 conditions:
1334
1335 - Trying to commit against a closed leaf: FSL_RC_ACCESS. Doing so
1336 is not permitted by fossil(1), so we disallow it here.
1337
1338 - An empty/NULL user name or commit message, or no files were
1339 selected which actually changed: FSL_RC_MISSING_INFO. In these
1340 cases f's error state describes the problem.
1341
1342 - Some resource is not found (e.g. an expected RID/UUID could not
1343 be resolved): FSL_RC_NOT_FOUND. This would generally indicate
1344 some sort of data consistency problem. i.e. it's quite possibly
1345 very bad if this is returned.
1346
1347 - If the checkin would result in no file-level changes vis-a-vis
1348 the current checkout, FSL_RC_NOOP is returned.
1349
1350 BUGS:
1351
1352 - It cannot currently properly distinguish a "no-op" commit, one in
1353 which no files were modified or only their permissions were
1354 modifed.
1355
1356 TODO:
1357
1358 - Honor the opt->dryRun flag. Getting this working has proven tricky
1359 because of stale cache issues.
1360
1361 @see fsl_checkin_enqueue()
1362 @see fsl_checkin_dequeue()
1363 @see fsl_checkin_discard()
1364 @see fsl_checkin_T_add()
1365*/
1367 fsl_id_t * newRid, fsl_uuid_str * newUuid);
1368
1369/**
1370 Works like fsl_deck_T_add(), adding the given tag information to
1371 the pending checkin state. Returns 0 on success, non-0 on error. A
1372 checkin may, in principal, have any number of tags, and this may be
1373 called any number of times to add new tags to the pending
1374 commit. This list of tags gets cleared by a successful
1375 fsl_checkin_commit() or by fsl_checkin_discard(). Decks require
1376 that each tag be distinct from each other (none may compare
1377 equivalent), but that check is delayed until the deck is output
1378 into its final artifact form.
1379
1380 @see fsl_checkin_enqueue()
1381 @see fsl_checkin_dequeue()
1382 @see fsl_checkin_commit()
1383 @see fsl_checkin_discard()
1384 @see fsl_checkin_T_add2()
1385*/
1387 fsl_uuid_cstr uuid, char const * name,
1388 char const * value);
1389
1390/**
1391 Works identically to fsl_checkin_T_add() except that it takes its
1392 argument in the form of a T-card object.
1393
1394 On success ownership of t is passed to mf. On error (see
1395 fsl_deck_T_add()) ownership is not modified.
1396
1397 Results are undefined if either argument is NULL or improperly
1398 initialized.
1399*/
1401
1402/**
1403 Clears all contents from f's checkout database, including the vfile
1404 table, vmerge table, and some of the vvar table. The tables are
1405 left intact. Returns 0 on success, non-0 if f has no checkout or for
1406 a database error.
1407*/
1409
1410/**
1411 Returns the base name of the current platform's checkout database
1412 file. That is "_FOSSIL_" on Windows and ".fslckout" everywhere
1413 else. The returned bytes are static.
1414
1415 TODO: an API which takes a dir name and looks for either name
1416*/
1418
1419/**
1420 File-overwrite policy values for use with fsl_ckup_opt and friends.
1421*/
1423/** Indicates that an error should be triggered if a file would be
1424 overwritten. */
1426/**
1427 Indicates that files should always be overwritten.
1428*/
1430/**
1431 Indicates that files should never be overwritten, and silently
1432 skipped over. This is almost never what one wants to do.
1433*/
1435};
1437
1438/**
1439 State values for use with fsl_ckup_state::fileRmInfo.
1440*/
1442/**
1443 Indicates that the file was not removed in a given checkout.
1444 Guaranteed to have the value 0 so that it is treated as boolean
1445 false. No other entries in this enum have well-defined values.
1446*/
1448/**
1449 Indicates that a file was removed from a checkout but kept
1450 in the filesystem because it was locally modified.
1451*/
1453/**
1454 Indicates that a file was removed from a checkout and the
1455 filesystem, with the caveat that failed attempts to remove from the
1456 filesystem are ignored for Reasons but will be reported as if the
1457 unlink worked.
1458*/
1460};
1462
1463/**
1464 Under construction. Work in progress...
1465
1466 Options for "opening" a fossil repository database. That is,
1467 creating a new fossil checkout database and populating its schema,
1468 _without_ checking out any files. (That latter part is up for
1469 reconsideration and this API might change in the future to check
1470 out files after creating/opening the db.)
1471*/
1473 /**
1474 Name of the target directory, which must already exist. May be
1475 relative, e.g. ".". The repo-open operation will chdir to this
1476 directory for the duration of the operation. May be NULL, in
1477 which case the current directory is assumed and no chdir is
1478 performed.
1479 */
1480 char const * targetDir;
1481
1482 /**
1483 The filename, with no directory components, of the desired
1484 checkout db name. For the time being, always leave this NULL and
1485 let the library decide. It "might" (but probably won't) be
1486 interesting at some point to allow the client to specify a
1487 different name (noting that that would be directly incompatible
1488 with fossil(1)).
1489 */
1490 char const * ckoutDbFile;
1491
1492 /**
1493 Policy for how to handle overwrites of files extracted from a
1494 newly-opened checkout.
1495
1496 Potential TODO: replace this with a fsl_confirmer, though that
1497 currently seems like overkill for this particular case.
1498 */
1500
1501 /**
1502 fsl_repo_open_ckout() installs the fossil checkout schema. If
1503 this is true it will forcibly replace any existing relevant
1504 schema components in the checkout db, otherwise it will fail when
1505 it tries to overwrite an existing schema and cannot.
1506 */
1508
1509 /**
1510 If true, the checkout-open process will look for an opened
1511 checkout in the target directory and its parents (recursively)
1512 and fail with FSL_RC_ALREADY_EXISTS if one is found.
1513 */
1515};
1517
1518/**
1519 Empty-initialized fsl_repo_open_ckout_opt const-copy constructer.
1520*/
1521#define fsl_repo_open_ckout_opt_m { \
1522 NULL/*targetDir*/, NULL/*ckoutDbFile*/, \
1523 FSL_OVERWRITE_ERROR/*fileOverwritePolicy*/, \
1524 false/*dbOverwritePolicy*/, \
1525 -1/*checkForOpenedCkout*/ \
1526}
1527
1528/**
1529 Empty-initialised fsl_repo_open_ckout_opt instance. Clients should copy
1530 this value (or fsl_repo_open_ckout_opt_empty_m) to initialise
1531 fsl_repo_open_ckout_opt instances for sane default values.
1532*/
1534
1535/**
1536 Opens a checkout db for use with the currently-connected repository
1537 or creates a new checkout db. If opening an existing one, it gets
1538 "stolen" from any repository it might have been previously mapped
1539 to.
1540
1541 - Requires that f have an opened repository db and no opened
1542 checkout. Returns FSL_RC_NOT_A_REPO if no repo is opened and
1543 FSL_RC_MISUSE if a checkout *is* opened.
1544
1545 - Creates/re-uses a .fslckout DB in the dir opt->targetDir. The
1546 directory must be NULL or already exist, else FSL_RC_NOT_FOUND is
1547 returned. If opt->dbOverwritePolicy is false then it fails with
1548 FSL_RC_ALREADY_EXISTS if that directory already contains a
1549 checkout db.
1550
1551 Note that this does not extract any SCM'd files from the
1552 repository, it only opens (and possibly creates) the checkout
1553 database.
1554
1555 Pending:
1556
1557 - If opening an existing checkout db for a different repo then
1558 delete the STASH and UNDO entries, as they're not valid for a
1559 different repo.
1560*/
1562 fsl_repo_open_ckout_opt const * opt );
1563
1565/**
1566 A callback type for use with fsl_ckup_state. It gets called via
1567 fsl_repo_ckout() and fsl_ckout_update() to report progress of the
1568 extraction process. It gets called after one of those functions has
1569 successfully extracted a file or skipped over it because the file
1570 existed and the checkout options specified to leave existing files
1571 in place. It must return 0 on success, and non-0 will end the
1572 extraction process, propagating that result code back to the
1573 caller. If this callback fails, the checkout's contents may be left
1574 in an undefined state, with some files updated and others not. All
1575 database-side data will be consistent (the transaction is rolled
1576 back) but filesystem-side changes may not be.
1577*/
1578typedef int (*fsl_ckup_f)( fsl_ckup_state const * cState );
1579
1580/**
1581 This enum lists the various types of individual file change states
1582 which can happen during a checkout, update, or merge.
1583*/
1585/** Sentinel value. */
1587/** Was unchanged between the previous and updated-to version,
1588 so no change was made to the on-disk file. This is the
1589 only entry in the enum which is guaranteed to have a specific
1590 value: 0, so that it can be used as a boolean false. */
1592/**
1593 Added to SCM in the updated-to version.
1594*/
1596/**
1597 Added to SCM in the current checkout version and carried over into
1598 the updated-to version.
1599*/
1601/**
1602 Removed from SCM in the updated-to to version OR in the checked-out
1603 version but not yet committed. a.k.a. it became "unmanaged."
1604
1605 Do we need to differentiate between those cases?
1606*/
1608/**
1609 Removed from the checked-out version but not yet commited,
1610 so was carried over to the updated-to version.
1611*/
1613/** Updated or replaced without a merge by the checkout/update
1614 process. */
1616/** Merge was not performed because at least one of the inputs appears
1617 to be binary. The updated-to version overwrites the previous
1618 version in this case.
1619*/
1621/** Updated with a merge by the update process. */
1623/** Special case of FSL_CKUP_FCHANGE_MERGED. Merge was performed
1624 and conflicts were detected. The newly-updated file will contain
1625 conflict markers.
1626
1627 @see fsl_buffer_contains_merge_marker()
1628*/
1630/** Added in the current checkout but also contained in the
1631 updated-to version. The local copy takes precedence.
1632*/
1634/**
1635 Added by the updated-to version but a local unmanaged copy exists.
1636 The local copy is overwritten, per historical fossil(1) convention
1637 (noting that fossil has undo support to allow one to avoid loss of
1638 such a file's contents).
1639
1640 TODO: use confirmer here to ask user whether to overwrite.
1641*/
1643/** Edited locally but removed from updated-to version. Local
1644 edits will be left in the checkout tree. */
1646/** Cannot merge if one or both of the update/updating verions of a
1647 file is a symlink. The updated-to version overwrites the previous
1648 version in this case.
1649
1650 We probably need a better name for this.
1651*/
1653/**
1654 Indicates that a merge of binary content was requested.
1655
1656 TODO: figure out why UPDATE uses the target version, instead of
1657 triggering an error here, and why MERGE does not do the same.
1658 fossil(1) simply skips over, with a warning, binaries during a
1659 merge.
1660*/
1662/** File was renamed in the updated-to version. If a file is both
1663 modified and renamed, it is flagged as renamed instead
1664 of modified. */
1666/** Locally modified. This state appears only when
1667 "updating" a checkout to the same version. */
1669};
1671
1672/**
1673 State to be passed to fsl_ckup_f() implementations via
1674 calls to fsl_repo_ckout() and fsl_ckout_update().
1675*/
1677 /**
1678 The core SCM state for the just-extracted file. Note that its
1679 content member will be NULL: the content is not passed on via
1680 this interface because it is only loaded for files which require
1681 overwriting.
1682
1683 An update process may synthesize content for extractState->fCard
1684 which do not 100% reflect the file on disk. Of primary note here:
1685
1686 1) fCard->uuid will refer to the hash of the updated-to
1687 version, as opposed to the hash of the on-disk file (which may
1688 differ due to having local edits merged in).
1689
1690 2) For the update process, fCard->priorName will be NULL unless
1691 the file was renamed between the original and updated-to
1692 versions, in which case priorName will refer to the original
1693 version's name.
1694 */
1696 /**
1697 Optional client-dependent state for use in the fsl_ckup_f()
1698 callback. This is copies from the corresponding
1699 fsl_ckup_opt::callbackState member.
1700 */
1702
1703 /**
1704 Vaguely describes the type of change the current call into
1705 the fsl_ckup_f() represents. The full range of values is
1706 not valid for all operations. Specifically:
1707
1708 Checkout only uses:
1709
1710 FSL_CKUP_FCHANGE_NONE
1711 FSL_CKUP_FCHANGE_UPDATED
1712 FSL_CKUP_FCHANGE_RM
1713
1714 For update operations all (or most) values are potentially
1715 possible.
1716
1717 If this has a value of FSL_CKUP_FCHANGE_RM,
1718 this->fileRmInfo will provide a bit more detail.
1719 */
1721
1722 /**
1723 Indicates whether the file was removed by the process:
1724
1725 - FSL_CKUP_RM_NOT = Was not removed.
1726
1727 - FSL_CKUP_RM_KEPT = Was removed from the checked-out version but
1728 left in the filesystem because the confirmer said to.
1729
1730 - FSL_CKUP_RM = Was removed from the checkout and the filesystem.
1731
1732 When this->dryRun is true, this specifies whether the file would
1733 have been removed.
1734 */
1736
1737 /**
1738 If fsl_repo_ckout()'s or fsl_ckout_update()'s options specified
1739 that the mtime should be set on each updated file, this holds
1740 that time. If the file existed and was not overwritten, it is set
1741 to that file's time. Else it is set to the current time (which
1742 may differ by a small fraction of a second from the file-write
1743 time because we avoid stat()'ing it again after writing). If
1744 this->fileRmInfo indicates that a file was removed, this might
1745 (depending on availability of the file in the filesystem at the
1746 time) be set to 0.
1747
1748 When running in dry-run mode, this value may be 0, as we may not
1749 have a file in place which we can stat() to get it, nor a db
1750 entry from which to fetch it.
1751
1752 This option is ignored for merge operations.
1753 */
1755
1756 /**
1757 The size of the extracted file, in bytes. If the file was removed
1758 from the filesystem (or removal was at least attempted) then this
1759 is set to -1.
1760 */
1762
1763 /**
1764 True if the current checkout/update is running in dry-run mode,
1765 else false. See fsl_ckup_opt::dryRun for details.
1766 */
1768};
1769
1770/**
1771 Options for use with fsl_repo_ckout() and
1772 fsl_ckout_update(). i.e. for checkout and update.
1773*/
1775 /**
1776 The version of the repostitory to check out or update. This must
1777 be the blob.rid of a checkin artifact.
1778 */
1780
1781 /**
1782 Gets called once per checked-out or updated file, passed a
1783 fsl_ckup_state instance with information about the
1784 checked-out file and related metadata. May be NULL.
1785 */
1787
1788 /**
1789 State to be passed to this->callback via the
1790 fsl_ckup_state::callbackState member.
1791 */
1793
1794 /**
1795 An optional "confirmer" for answering questions about file
1796 overwrites and deletions posed by the checkout process.
1797 By default this confirmer of the associated fsl_cx instance
1798 is used.
1799
1800 Caveats:
1801
1802 - This is not currently used by the update process, only
1803 checkout.
1804
1805 - If this->setMTime is true, the mtime is NOT set for any files
1806 which already exist and are skipped due to the confirmer saying
1807 to leave them in place.
1808
1809 - Similarly, if the confirmer says to never overwrite files,
1810 permissions on existing files are not modified. fsl_repo_ckout()
1811 does not (re)write unmodified files, and thus may leave such
1812 files with different permissions. That's on the to-fix list.
1813 */
1815
1816 /**
1817 If true, the checkout/update processes will calculate the
1818 (synthetic) mtime of each extracted file and set its mtime. This
1819 is a relatively expensive operation which calculates the
1820 "effective mtime" of each file by calculating it: Fossil does not
1821 record file timestamps, instead treating files as if they had the
1822 timestamp of the most recent checkin in which they were added or
1823 modified.
1824
1825 It's generally a good idea to let the update process stamp the
1826 _current_ time on modified files, in order to avoid any hiccups
1827 with build processes which rely on accurate times
1828 (e.g. Makefiles). When doing a clean checkout, it's often
1829 interesting to see the "original" times, though.
1830 */
1832
1833 /**
1834 A hint to fsl_repo_ckout() and fsl_ckout_update() about whether
1835 it needs to scan the checkout for changes. Set this to false ONLY
1836 if the calling code calls fsl_ckout_changes_scan() (or
1837 equivalent, e.g. fsl_vfile_changes_scan()) immediately before
1838 calling fsl_repo_ckout() or fsl_ckout_update(), as those require
1839 a non-stale changes scan in order to function properly.
1840 */
1842
1843 /**
1844 If true, the extraction process will "go through the motions" but
1845 will not write any files to disk. It will perform I/O such as
1846 stat()'ing to see, e.g., if it would have needed to overwrite a
1847 file.
1848 */
1850};
1852
1853/**
1854 Empty-initialized fsl_ckup_opt const-copy constructor.
1855*/
1856#define fsl_ckup_opt_m {\
1857 -1/*checkinRid*/, NULL/*callback*/, NULL/*callbackState*/, \
1858 fsl_confirmer_empty_m/*confirmer*/,\
1859 false/*setMtime*/, true/*scanForChanges*/,false/*dryRun*/ \
1860}
1861
1862/**
1863 Empty-initialised fsl_ckup_opt instance. Clients should copy
1864 this value (or fsl_ckup_opt_empty_m) to initialise
1865 fsl_ckup_opt instances for sane default values.
1866*/
1868
1869/**
1870 A fsl_repo_extract() proxy which extracts the contents of the
1871 repository version specified by opt->checkinRid to the root
1872 directory of f's currently-opened checkout. i.e. it performs a
1873 "checkout" operation.
1874
1875 For each extracted entry, cOpt->callback (if not NULL) will be
1876 passed a (fsl_ckup_state const*) which contains a pointer
1877 to the fsl_repo_extract_state and some additional metadata
1878 regarding the extraction. The value of cOpt->callbackState will be
1879 set as the callbackState member of that fsl_ckup_state
1880 struct, so that the client has a way of passing around app-specific
1881 state to that callback.
1882
1883 After successful completion, the process will report (see below)
1884 any files which were part of the previous checkout version but are
1885 not part of the current version, optionally removing them from the
1886 filesystem (depending on the value of opt->rmMissingPolicy). It
1887 will IGNORE ANY DELETION FAILURE of files it attempts to
1888 delete. The reason it does not fail on removal error is because
1889 doing so would require rolling back the transaction, effectively
1890 undoing the checkout, but it cannot roll back any prior deletions
1891 which succeeded. Similarly, after all file removal is complete, it
1892 attempts to remove any now-empty directories left over by that
1893 process, also silently ignoring any errors. If the cOpt->dryRun
1894 option is specified, it will "go through the motions" of removing
1895 files but will not actually attempt filesystem removal. For
1896 purposes of the callback, however, it will report deletions as
1897 having happened (but will also set the dryRun flag on the object
1898 passed to the callback).
1899
1900 After unpacking the SCM-side files, it may write out one or more
1901 manifest files, as described for fsl_ckout_manifest_write(), if the
1902 'manifest' config setting says to do so.
1903
1904 As part of the file-removal process, AFTER all "existing" files are
1905 processed, it calls cOpt->callback() (if not NULL) for each removed
1906 file, noting the following peculiarities in the
1907 fsl_ckup_state object which is passed to it for those
1908 calls:
1909
1910 - It is called after the processing of "existing" files. Thus the
1911 file names passed during this step may appear "out of order" with
1912 regards to the others (which are guaranteed to be passed in lexical
1913 order, though whether it is case-sensitive or not depends on the
1914 repository's case-sensitivity setting).
1915
1916 - fileRmInfo will indicate that the file was removed from the
1917 checkout, and whether it was actually removed or retained in the
1918 filesystem. This will indicate filesystem-level removal even when
1919 in dry-run mode, though in that case no filesystem-level removal is
1920 actually attempted.
1921
1922 - extractState->fileRid will refer to the file's blob's RID for the
1923 previous checkout version.
1924
1925 - extractState->content will be NULL.
1926
1927 - extractState->callbackState will be NULL.
1928
1929 - extractState->fCard will refer to the pre-removal state of the
1930 file. i.e. the state as it was in the checkout prior to this
1931 function being called.
1932
1933 Returns 0 on success. Returns FSL_RC_NOT_A_REPO if f has no opened
1934 repo, FSL_RC_NOT_A_CKOUT if no checkout is opened. If
1935 cOpt->callback is not NULL and returns a non-0 result code,
1936 extraction ends and that result is returned. If it returns non-0 at
1937 any point after basic argument validation, it rolls back all
1938 changes or sets the current transaction stack into a rollback
1939 state.
1940
1941 @see fsl_repo_open_ckout()
1942*/
1944
1945
1946/**
1947 UNDER CONSTRUCTION.
1948
1949 Performs an "update" operation on f's currenly-opened
1950 checkout. Performing an update is similar to performing a checkout,
1951 the primary difference being that an update will merge local file
1952 modifications into any newly-updated files, whereas a checkout will
1953 overwrite them.
1954
1955 TODO?: fossil(1)'s update permits a list of files, in which case it
1956 behaves differently: it updates the given files to the version
1957 requested but leaves the checkout at its current version. To be
1958 able to implement that we either need clients to call this in a
1959 loop, changing opt->filename on each call (like how we do
1960 fsl_ckout_manage()) or we need a way for them to pass on the list
1961 of files/dir in the opt object.
1962
1963 @see fsl_repo_ckout().
1964*/
1966
1967
1968/**
1969 Tries to calculate a version to update the current checkout version
1970 to, preferring the tip of the current checkout's branch.
1971
1972 On success, 0 is returned and *outRid is set to the calculated RID,
1973 which may be 0, indicating that no errors were encountered but no
1974 version could be calculated.
1975
1976 On error, non-0 is returned, outRid is not modified, and f's error
1977 state is updated.
1978
1979 Returns FSL_RC_NOT_A_CKOUT if f has no checkout opened and
1980 FSL_RC_NOT_A_REPO if no repo is opened.
1981
1982 If it calculates that there are multiple viable descendants it
1983 returns FSL_RC_AMBIGUOUS and f's error state will contain a list of
1984 the UUIDs (or UUID prefixes) of those descendants.
1985
1986 Sidebar: to get the absolute latest version, irrespective of the
1987 branch, use fsl_sym_to_rid() to resolve the symbolic name "tip".
1988*/
1990
1991/**
1992 Bitmask used by fsl_ckout_manifest_setting() and
1993 fsl_ckout_manifest_write().
1994*/
1996/** Coresponds to the file "manifest". */
1998/** Coresponds to the file "manifest.uuid". */
2000/** Coresponds to the file "manifest.tags". */
2002};
2004
2005/**
2006 Returns a bitmask representing which manifest files, if any, will
2007 be written when opening or updating a checkout directory, as
2008 specified by the repository's 'manifest' configuration setting, and
2009 sets *m to a bitmask indicating which of those are enabled. It
2010 first checks for a versioned setting then, if no versioned setting
2011 is found, a repository-level setting.
2012
2013 A truthy setting value (1, "on", "true") means to write the
2014 manifest and manifest.uuid files. A string with any of the letters
2015 'r', 'u', or 't' means to write the [r]aw, [u]uid, and/or [t]ags
2016 file(s), respectively.
2017
2018 If the manifest setting is falsy or not set, *m is set to 0, else
2019 *m is set to a bitmask representing which file(s) are considered to
2020 be auto-generated for this repository:
2021
2022 - FSL_MANIFEST_MAIN = manifest
2023 - FSL_MANIFEST_UUID = manifest.uuid
2024 - FSL_MANIFEST_TAGS = manifest.tags
2025
2026 Any db-related or allocation errors while trying to fetch the
2027 setting are silently ignored.
2028
2029 For performance's sake, since this is potentially called often from
2030 fsl_reserved_fn_check(), this setting is currently cached by this
2031 routine (in the fsl_cx object), but that ignores the fact that the
2032 manifest setting can be modified at any time, either in a versioned
2033 setting file or the repository db, and may be modified from outside
2034 the library. There's a tiny back-door for working around that: if m
2035 is NULL, the cache will be flushed and no other work will be
2036 performed. Thus the following approach can be used to force a fresh
2037 check for that setting:
2038
2039 ```
2040 fsl_ckout_manifest_setting(f, NULL); // clears caches, does nothing else
2041 fsl_ckout_manifest_setting(f, &myInt); // loads/caches the setting
2042 ```
2043*/
2045
2046/**
2047 Might write out the files manifest, manifest.uuid, and/or
2048 manifest.tags for the current checkout to the the checkout's root
2049 directory. The 2nd-4th arguments are interpreted as follows:
2050
2051 0: Do not write that file.
2052
2053 >0: Always write that file.
2054
2055 <0: Use the value of the "manifest" config setting (see
2056 fsl_ckout_manifest_setting()) to determine whether or not to write
2057 that file.
2058
2059 As each file is written, its mtime is set to that of the checkout
2060 version. (Forewarning: that behaviour may change if it proves to be
2061 problematic vis a vis build processes.)
2062
2063 Returns 0 on success, non-0 on error:
2064
2065 - FSL_RC_NOT_A_CKOUT if no checkout is opened.
2066
2067 - FSL_RC_RANGE if the current checkout RID is 0 (indicating a fresh,
2068 empty repository).
2069
2070 - Various potential DB/IO-related error codes.
2071
2072 If the final argument is not NULL then it will be updated to
2073 contain a bitmask representing which files, if any, were written:
2074 see fsl_ckout_manifest_setting() for the values. It is updated
2075 regardless of success or failure and will indicate which file(s)
2076 was/were written before the error was triggered.
2077
2078 Each file implied by the various manifest settings which is NOT
2079 written by this routine and is also not part of the current
2080 checkout (i.e. not listed in the vfile table) will be removed from
2081 disk, but a failure while attempting to do so will be silently
2082 ignored.
2083
2084 @see fsl_repo_manifest_write()
2085*/
2087 int manifest,
2088 int manifestUuid,
2089 int manifestTags,
2090 int * const wroteWhat );
2091
2092/**
2093 Returns true if f has an opened checkout and the given absolute
2094 path is rooted in that checkout, else false. As a special case, it
2095 returns false if the path _is_ the checkout root unless zAbsPath
2096 has a trailing slash. (The checkout root is always stored with a
2097 trailing slash because that simplifies its internal usage.)
2098
2099 Note that this is strictly a string comparison, not a
2100 filesystem-level operation.
2101*/
2102FSL_EXPORT bool fsl_is_rooted_in_ckout(fsl_cx * const f, char const * const zAbsPath);
2103
2104/**
2105 Works like fsl_is_rooted_in_ckout() except that it returns 0 on
2106 success, and on error updates f with a description of the problem
2107 and returns non-0: FSL_RC_RANGE or (if updating the error state
2108 fails) FSL_RC_OOM.
2109 */
2110FSL_EXPORT int fsl_is_rooted_in_ckout2(fsl_cx * const f, char const * const zAbsPath);
2111
2112/**
2113 Change-type values for use with fsl_ckout_revert_f() callbacks.
2114*/
2116/** Sentinel value. */
2118/**
2119 File was previously queued for addition but unqueued
2120 by the revert process.
2121*/
2123/**
2124 File was previously queued for removal but unqueued by the revert
2125 process. If the file's contents or permissions were also reverted
2126 then the file is reported as FSL_REVERT_PERMISSIONS or
2127 FSL_REVERT_CONTENTS instead.
2128*/
2130/**
2131 File was previously scheduled to be renamed, but the rename was
2132 reverted. The name reported to the callback is the original one.
2133 If a file was both modified and renamed, it will be flagged as
2134 renamed instead of modified, for consistency with the usage of
2135 fsl_ckup_fchange_e's FSL_CKUP_FCHANGE_RENAMED.
2136
2137 FIXME: this does not mean that the file on disk was actually
2138 renamed (if needed). That is TODO, pending addition of code to
2139 perform renames.
2140*/
2142/** File's permissions (only) were reverted. */
2144/**
2145 File's contents reverted. This value trumps any others in this
2146 enum. Thus if a file's permissions and contents were reverted,
2147 or it was un-renamed and its contents reverted, it will be
2148 reported using this enum entry.
2149*/
2151};
2153/**
2154 Callback type for use with fsl_ckout_revert(). For each reverted
2155 file it gets passed the checkout-relative filename, type of change,
2156 and the callback state pointer which was passed to
2157 fsl_ckout_revert(). If it returns non-0, the revert process will
2158 end in an error and that code will be propagated back to the
2159 caller. In such cases, any files reverted up until that point will
2160 still be reverted on disk but the reversion in the database will be
2161 rolled back. A change scan (e.g. fsl_ckout_changes_scan()) will
2162 restore balance to that equation, but these callbacks should only
2163 return non-0 in for catastrophic failure.
2164*/
2165typedef int (*fsl_ckout_revert_f)( char const *zFilename,
2166 fsl_ckout_revert_e changeType,
2167 void * callbackState );
2168
2169/**
2170 Options for passing to fsl_ckout_revert().
2171*/
2173 /**
2174 File or directory name to revert. See also this->vfileIds.
2175 */
2176 char const * filename;
2177 /**
2178 An alternative to assigning this->filename is to point
2179 this->vfileIds to a bag of vfile.id values. If this member is not
2180 NULL, fsl_ckout_revert() will ignore this->filename.
2181
2182 @see fsl_filename_to_vfile_ids()
2183 */
2185 /**
2186 Interpret filename as relative to cwd if true, else relative to
2187 the current checkout root. This is ignored when this->vfileIds is
2188 not NULL.
2189 */
2191 /**
2192 If true, fsl_vfile_changes_scan() is called to ensure that
2193 the filesystem and vfile tables agree. If the client code has
2194 called that function, or its equivalent, since any changes were
2195 made to the checkout then this may be set to false to speed up
2196 the revert process.
2197 */
2199
2200 /**
2201 Optional callback to notify the client of what gets reverted.
2202 */
2204 /**
2205 State for this->callback.
2206 */
2208};
2210/**
2211 Initialized-with-defaults fsl_ckout_revert_opt instance,
2212 intended for use in const-copy initialization.
2213*/
2214#define fsl_ckout_revert_opt_empty_m { \
2215 NULL/*filename*/,NULL/*vfileIds*/,true/*relativeToCwd*/,true/*scanForChanges*/, \
2216 NULL/*callback*/,NULL/*callbackState*/ \
2217}
2218/**
2219 Initialized-with-defaults fsl_ckout_revert_opt instance,
2220 intended for use in non-const copy initialization.
2221*/
2223
2224/**
2225 Reverts changes to checked-out files, replacing their
2226 on-disk versions with the current checkout's version.
2227
2228 If zFilename refers to a directory, all managed files under that
2229 directory are reverted (if modified). If zFilename is NULL or
2230 empty, all modifications in the current checkout are reverted.
2231
2232 If a file has been added but not yet committed, the add
2233 is un-queued but the file is otherwise untouched. If the
2234 file has been queued for removal, this removes it from
2235 that queue as well as restores its contents.
2236
2237 If a rename is pending for the given filename, the name may match
2238 either its original name or new name. Whether or not that will
2239 actually work when file A is renamed to B and file C is renamed to
2240 A is anyone's guess. (Noting that (fossil mv) won't allow that
2241 situation to exist in the vfile table for a single checkout
2242 version, so it seems safe enough.)
2243
2244 If the 4th argument is not NULL then it is called for each revert
2245 (_after_ the revert happens) to report what was done with that
2246 file. It gets passed the checkout-relative name of each reverted
2247 file. The 5th argument is not interpreted by this function but is
2248 passed on as-is as the final argument to the callback. If the
2249 callback returns non-0, the revert process is cancelled, any
2250 pending transaction is set to roll back, and that error code is
2251 returned. Note that cancelling a revert mid-process will leave file
2252 changes made by the revert so far in place, and thus the checkout
2253 db and filesystem will be in an inconsistent state until
2254 fsl_vfile_changes_scan() (or equivalent) is called to restore
2255 balance to the world.
2256
2257 Files which are not actually reverted because their contents or
2258 permissions were not modified on disk are not reported to the
2259 callback unless the reversion was the un-queuing of an ADD or
2260 REMOVE operation.
2261
2262 Returns 0 on success, any number of non-0 results on error.
2263
2264 [tag:bug:revert-merge-hiccup] (2024-09-13): it is possible, via
2265 merging and copying modified files between multiple checkouts of
2266 the same repo, to get the tree into a state where this function has
2267 no files to revert and therefore does not clear the merge
2268 state. This condition is very tricky to trigger, and has only been
2269 seen once in the wild. "The problem" with fixing that is that
2270 whether or not we need to do a _full_ wipe of the merge state (as
2271 opposed to just wiping merge state of individual files) depends
2272 largely on information which (A) this function does have and (B) is
2273 onerous for the caller to figure out and provide (namely, whether
2274 it's a full revert or not). As this bug is so rare, we'll leave it
2275 for now and ponder potential solutions. As of 2024-09-13, this bug
2276 is believed to have been adequately resolved, but exactly how it
2277 was initially triggered is unclear, so we don't have a test which
2278 proves it is resolved.
2279*/
2281 fsl_ckout_revert_opt const * opt );
2282
2283/**
2284 Expects f to have an opened checkout and zName to be the name of
2285 an entry in the vfile table where vfile.vid == vid. If vid<=0 then
2286 the current checkout RID is used. This function does not do any
2287 path resolution or normalization on zName and checks only for an
2288 exact match (honoring f's case-sensitivity setting - see
2289 fsl_cx_case_sensitive_set()).
2290
2291 On success it returns 0 and assigns *vfid to the vfile.id value of
2292 the matching file. If no match is found, 0 is returned and *vfile
2293 is set to 0. Returns FSL_RC_NOT_A_CKOUT if no checkout is opened,
2294 FSL_RC_RANGE if zName is not a simple path (see
2295 fsl_is_simple_pathname()), and any number of codes for db-related
2296 errors.
2297
2298 This function matches only vfile.pathname, not vfile.origname,
2299 because it is possible for a given name to be in both fields (in
2300 different records) at the same time.
2301*/
2303 char const * zName,
2304 fsl_id_t * const vfid );
2305
2306/**
2307 Searches the `vfile` table where `vfile.vid=vid` for a name which
2308 matches `zName` or all `vfile` entries found under a subdirectory
2309 named `zName` (with no trailing slash). `zName` must be relative to
2310 the checkout root. As a special case, if `zName` is `NULL`, empty,
2311 or `"."` then all files in `vfile` with the given `vid` are
2312 selected. For each entry it finds, it adds the `vfile.id` to
2313 `dest`. If `vid<=0` then the current checkout RID is used.
2314
2315 If `changedOnly` is `true` then only entries which have been marked
2316 in the `vfile` table as having some sort of change are included, so
2317 if `true` then fsl_ckout_changes_scan() (or equivalent) must have
2318 been "recently" called to ensure that state is up to do. This routine
2319 only checks the `vfile` table for "is changed" state, it does not
2320 do filesystem-level checks on the files.
2321
2322 This search honors the context-level case-sensitivity setting (see
2323 fsl_cx_case_sensitive_set()).
2324
2325 Returns 0 on success. Not finding anything is not treated as an
2326 error, though we could arguably return `FSL_RC_NOT_FOUND` for the
2327 cases which use this function. In order to determine whether or not
2328 any results were actually found, compare `dest->entryCount` before
2329 and after calling this.
2330
2331 This function matches only `vfile.pathname`, not `vfile.origname`,
2332 because it is possible for a given name to be in both fields (in
2333 different records) at the same time.
2334
2335 @see fsl_ckout_vfile_ids()
2336*/
2338 fsl_id_bag * const dest,
2339 char const * zName,
2340 bool changedOnly);
2341
2342/**
2343 This is a variant of fsl_filename_to_vfile_ids() which accepts
2344 filenames in a more flexible form than that routine. This routine
2345 works exactly like that one except for the following differences:
2346
2347 1) The given filename and the relativeToCwd arguments are passed to
2348 by fsl_ckout_filename_check() to canonicalize the name and ensure
2349 that it points to someplace within f's current checkout.
2350
2351 2) Directory names passed to it may optionally end in an trailing
2352 slash.
2353
2354 3) Because of (1), zName may not be NULL or empty. To fetch all of
2355 the vfile IDs for the current checkout, pass a zName of "." and
2356 relativeToCwd=false.
2357
2358 Returns 0 on success, else:
2359
2360 - FSL_RC_MISUSE if zName is NULL or empty.
2361 - FSL_RC_OOM on allocation error.
2362 - FSL_RC_NOT_A_CKOUT if f has no opened checkout.
2363 - FSL_RC_RANGE if the given name points outside of the checkout.
2364*/
2366 fsl_id_bag * const dest, char const * zName,
2367 bool relativeToCwd, bool changedOnly );
2368
2369
2370/**
2371 This "mostly internal" routine (re)populates f's checkout vfile
2372 table with all files from the given checkin manifest. If
2373 manifestRid is 0 or less then the current checkout's RID is
2374 used. If vfile already contains any content for the given checkin,
2375 it is left intact (and several processes rely on that behavior to
2376 keep it from nuking, e.g., as-yet-uncommitted queued add/rm
2377 entries).
2378
2379 Returns 0 on success, any number of codes on any of many potential
2380 errors.
2381
2382 f must not be NULL and must have opened checkout and repository
2383 databases. In debug builds it will assert that that is so.
2384
2385 If the 3rd argument is true, any entries in vfile for checkin
2386 versions other than the one specified in the 2nd argument are
2387 cleared from the vfile table. That is _almost_ always the desired
2388 behavior, but there are rare cases where vfile needs to temporarily
2389 (for the duration of a single transaction) hold state for multiple
2390 versions.
2391
2392 If the 4th argument is not NULL, it gets assigned the number of
2393 blobs from the given version which are currently missing from the
2394 repository due to being phantoms (as opposed to being shunned).
2395
2396 Returns 0 on success, FSL_RC_NOT_A_CKOUT if no checkout is opened,
2397 FSL_RC_OOM on allocation error, FSL_RC_DB for db-related problems,
2398 et.al.
2399
2400 Misc. notes:
2401
2402 - This does NOT update the "checkout" vvar table entry because this
2403 routine is sometimes used in contexts where we need to briefly
2404 maintain two vfile versions and keep the previous checkout version.
2405
2406 - Apps must take care to not leave more than one version in the
2407 vfile table for longer than absolutely needed. They "really should"
2408 use fsl_vfile_unload() to clear out any version they load with this
2409 routine.
2410
2411 @see fsl_vfile_unload()
2412 @see fsl_vfile_unload_except()
2413*/
2414FSL_EXPORT int fsl_vfile_load(fsl_cx * const f, fsl_id_t manifestRid,
2415 bool clearOtherVersions,
2416 uint32_t * missingCount);
2417
2418/**
2419 Clears out all entries in the current checkout's vfile table with
2420 the given vfile.vid value. If vid<=0 then the current checkout RID
2421 is used (which is never a good idea from client-side code!).
2422
2423 ACHTUNG: never do this without understanding the consequences. It
2424 can ruin the current checkout state.
2425
2426 Returns 0 on success, FSL_RC_NOT_A_CKOUT if f has no checkout
2427 opened, FSL_RC_DB on any sort of db-related error (in which case
2428 f's error state is updated with a description of the problem).
2429
2430 @see fsl_vfile_load()
2431 @see fsl_vfile_unload_except()
2432*/
2434
2435/**
2436 A counterpart of fsl_vfile_unload() which removes all vfile
2437 entries where vfile.vid is not the given vid. If vid is <=0 then
2438 the current checkout RID is used.
2439
2440 Returns 0 on success, FSL_RC_NOT_A_CKOUT if f has no checkout
2441 opened, FSL_RC_DB on any sort of db-related error (in which case
2442 f's error state is updated with a description of the problem).
2443
2444 @see fsl_vfile_load()
2445 @see fsl_vfile_unload()
2446*/
2448
2449
2450/**
2451 Performs a "fingerprint check" between f's current checkout and
2452 repository databases. Returns 0 if either there is no checkout, no
2453 mismatch, or it is impossible to determine because the checkout is
2454 missing a fingerprint (which is legal for "older" checkout
2455 databases).
2456
2457 If a mismatch is found, FSL_RC_REPO_MISMATCH is returned. Returns
2458 some other non-0 code on a lower-level error (db access, OOM,
2459 etc.).
2460
2461 As a special case, this is a no-op for a newly-created repo, as
2462 those cannot yet have a fingerprint.
2463
2464 A mismatch can happen when the repository to which a checkout
2465 belongs is replaced, either with a completely different repository
2466 or a copy/clone of that same repository. Each repository copy may
2467 have differing blob.rid values, and those are what the checkout
2468 database uses to refer to repository-side data. If those RIDs
2469 change, then the checkout is left pointing to data other than what
2470 it should be.
2471
2472 TODO: currently the library offers no automated recovery mechanism
2473 from a mismatch, the only remedy being to close the checkout
2474 database, destroy it, and re-create it. fossil(1) is able, in some cases,
2475 to automatically recover from this situation.
2476*/
2478
2479/**
2480 Looks for the given file in f's current checkout. If relativeToCwd
2481 then the name is resolved from the current directory, otherwise it is
2482 assumed to be relative to the checkout root or an absolute path
2483 with the checkout dir as a prefix of that path.
2484
2485 On success, 0 is returned and dest's gets populated with the
2486 content of the file.
2487
2488 On error, non-0 is returned and, depending on the error type, dest
2489 might be partially populated. f's error state will be updated to
2490 describe the error.
2491
2492 Results are undefined if any pointer argument is NULL.
2493
2494 This function currently resolves symlinks on its way to the
2495 content, but that behaviour may change in the future to reflect f's
2496 symlink preferences.
2497*/
2499 char const * zName,
2500 fsl_buffer * const dest);
2501
2502/**
2503 Fetches the timestamp of the given F-card's name against the
2504 filesystem and/or the most recent checkin in which it was modified
2505 (as reported by fsl_mtime_of_manifest()). vid is the checkin
2506 version to look at. If it's <=0, the current checkout will be used.
2507
2508 On success, returns 0 and:
2509
2510 - If repoMtime is not NULL then (*repoMtime) is assigned to the
2511 result of fsl_mtime_of_manifest_file() for the given file.
2512
2513 - If localMtime is not NULL then (*localMtime) is assigned to
2514 the checkout-local timestamp of the file.
2515
2516 Returns non-0 on error. Some of the potential results include:
2517
2518 - FSL_RC_NOT_A_CKOUT.
2519
2520 - FSL_RC_NOT_FOUND if the filename cannot be resolved in the
2521 requested version or cannot be stat()'d. This can happen if,
2522 e.g. fc's file has been renamed, but not yet checked in, in the
2523 current checkout. A _potential_ TODO is to check for a
2524 (`vfile.origname=fc->name`) record and use `vfile.pathname` for
2525 the stat() call.
2526
2527 - FSL_RC_OOM.
2528*/
2530 fsl_card_F const * const fc,
2531 fsl_time_t * const repoMtime,
2532 fsl_time_t * const localMtime);
2533
2534/**
2535 File change types for use with fsl_merge_state::fileChangeType.
2536
2537 Terminology used in some of the descriptions:
2538
2539 - (P) is the "pivot" - the common ancestor for the merge.
2540 - (M) is the version being merged in to...
2541 - (V) is current checkout version into which (M) is being merged.
2542
2543 Maintenance reminder: this enum's values must start at 0 and
2544 increment sequentially, and FSL_MERGE_FCHANGE_count must be the
2545 final entry. This is to enable the creation of arrays, e.g. for
2546 keeping track (client-side) of how many times a given change type
2547 has been seen during a given merge run.
2548*/
2550/**
2551 Not currently used. Merge does not (and cannot without some
2552 surgery) report state of files unaffected by a merge. This entry
2553 exists for the case that that changes. This is the only entry in
2554 the enum which is guaranteed to have a specific value: 0, so that
2555 it can be used as a boolean false. */
2557/**
2558 File was added to (V) from (M).
2559*/
2561/**
2562 File content was copied as-is from (M) to (V).
2563*/
2565/**
2566 File was removed from (V) via (M). a.k.a. it became "unmanaged."
2567*/
2569/**
2570 Content from (M) was merged into (V).
2571*/
2573/**
2574 Special case of FSL_MERGE_FCHANGE_MERGED. Merge was performed from
2575 (M) to (V) and conflicts were detected. The newly-updated file will
2576 contain conflict markers.
2577
2578 @see fsl_buffer_contains_merge_marker()
2579*/
2581#if 0
2582/** Added in the current checkout but also contained in the
2583 updated-to version. The local copy takes precedence.
2584*/
2585FSL_MERGE_FCHANGE_CONFLICT_ADDED,
2586#endif
2587/**
2588 Added to (V) by (M) but a local unmanaged copy exists.
2589 The local copy is overwritten, per historical fossil(1) convention
2590 (noting that fossil has undo support to allow one to avoid loss of
2591 such a file's contents).
2592*/
2594#if 0
2595/*
2596 Fossil deletes merged-over removed files, regardless of whether
2597 they're locally edited, so we'll do the same for now (noting that
2598 fossil has undo support which can hypothetically save that case
2599 from data loss). fsl_ckout_update() does not do so, but has extra
2600 infastructure to deal with this. */
2601/** Edited locally but removed from merged-in version. Local
2602 edits will be left in the checkout tree. */
2603FSL_MERGE_FCHANGE_CONFLICT_RM,
2604#endif
2605/**
2606 Cannot merge if one or both of the update/updating versions of a
2607 file is a symlink.
2608
2609 This case needs re-thinking. fossil(1) simply skips such merges
2610 with a warning but no error. This library has no warning mechanism
2611 other than to pass this code on to the fsl_merge_f() callback,
2612 so that's what we do.
2613
2614 For UPDATE ops, the updated-to version overwrites the previous
2615 version in this case. Why merge doesn't do that isn't clear, but
2616 it's probably because we can have any number of merge parents and
2617 choosing which one to use in the merge/replace case would be
2618 impossible.
2619*/
2621/**
2622 Indicates that a merge of binary content was requested. We
2623 cannot merge binaries, so this indicates that the file in question
2624 was skipped over for merge purposes.
2625
2626 fossil(1) simply skips over, with a warning, binaries during a
2627 merge, so we do the same (for lack of a better option).
2628*/
2630/**
2631 File was renamed in the updated-to version. If a file is both
2632 modified and renamed, it will be reported twice: once for each type
2633 of change. The new name is reported via fsl_merge_state::filename
2634 and the previous name via fsl_merge_state::priorName.
2635*/
2637/**
2638 This is the number of entries in this enum, for purposes of creating,
2639 e.g. arrays of counters. This entry is never reported via a
2640 fsl_merge_state::fileChangeType.
2641*/
2643};
2645
2646/** Reqired forward decl. */
2648
2649/**
2650 UNDER CONSTRUCTION! INCOMPLETE!
2651
2652 A type for passing state to fsl_merge_f callbacks during
2653 fsl_ckout_merge() processing.
2654
2655 For each step of a merge operation which affects a file,
2656 state reflecting that change is set in one of these objects
2657 and it is passed to the fsl_merge_f implementation supplied by
2658 the caller.
2659
2660 Unlike fsl_ckout_update(), fsl_ckout_merge() reports only files
2661 which are affected by a merge, not unmodified files. Whether
2662 that's a bug or a feature is not yet clear, but the merge algorithm
2663 does not, as is, support reporting unaffected files.
2664
2665 Due to the complexity and intricacy of the merge operation, it is
2666 possible that any given file will get passed to the fsl_merge_f()
2667 callback more than once with a different
2668 fsl_merge_state::fileChangeType value. Most notably, a file which
2669 has been modified and renamed may be passed on one with
2670 FSL_MERGE_FCHANGE_COPIED and once with FSL_MERGE_FCHANGE_RENAMED.
2671 Whether that's a bug or a feature is as-yet undecided, but
2672 (A) fossil(1) does it that way and (B) _not_ doing that would
2673 require some rearchitecting.
2674*/
2676 /**
2677 The fsl_cx object for which the current merge is running.
2678 */
2680 /**
2681 The options object which drives the current fsl_ckout_merge()
2682 run.
2683 */
2685
2686 /**
2687 The checkout-relative name of the file affected by the merge.
2688 These bytes are invalidated after the fsl_merge_f() callback
2689 returns, so must be copied if the client requires them for later.
2690 */
2691 char const * filename;
2692
2693 /**
2694 If this->fileChangeType is FSL_MERGE_FCHANGE_RENAMED then
2695 this is the previous name of the file, else it is NULL.
2696 */
2697 char const * priorName;
2698
2699 /**
2700 Indicates the state of the file currently being merged. Merge
2701 does not support the full range fo fsl_ckup_fchange_e
2702 values. TODO: list which it does or create a new enum which
2703 enumerates only merge-specific change types.
2704 */
2706
2707 /**
2708 Indicates whether the current file was removed. A state of
2709 FSL_CKUP_RM_KEPT and fileChangeType of FSL_MERGE_FCHANGE_RM
2710 indicates that the file has become unmanaged but the local
2711 copy was retained because it was flagged as locally modified.
2712 */
2714};
2716
2717/**
2718 Callback type for use with fsl_merge_opt and fsl_ckout_merge().
2719*/
2720typedef int (*fsl_merge_f)(fsl_merge_state const * const);
2721
2722/**
2723 Merge type enum for use with fsl_merge_opt::mergeType.
2724
2725 The values of these entries are fossil-magic values for the
2726 `vmerge.id` db field and must stay in sync with fossil's
2727 definition.
2728*/
2730/**
2731 Indicates a normal merge.
2732*/
2734/**
2735 Indicates an "integrate" merge, which tells the next checkin
2736 operation to apply a "closed" tag to the checkin from which this
2737 merge is performed (effectively closing its branch).
2738
2739 Certain merge-time state will force this merge type to silently
2740 behave like FSL_MERGE_TYPE_NORMAL:
2741
2742 - If the being-merged-in content is marked as private.
2743 - If the being-merged-in content is not a leaf.
2744*/
2746/**
2747 Indicates a cherrypick merge, pulling in only the changes made to a
2748 specific checkin without otherwise inheriting its lineage.
2749*/
2751/**
2752 Indicates a backout merge, a reverse cherrypick, backing out any
2753 changes which were added by the corresponding
2754 fsl_merge_opt::mergeRid.
2755*/
2757};
2759
2760/**
2761 UNDER CONSTRUCTION.
2762
2763 Options for use with fsl_ckout_merge().
2764*/
2766 /**
2767 The version of the repostitory to merge into the current
2768 checkout. This must be the `blob.rid` of a checkin artifact.
2769 */
2771 /**
2772 The version of the most recent common ancestor. Must normally be
2773 0. The default is calculated automatically based on
2774 this->mergeRid and this->mergeType.
2775
2776 This corresponds to fossil(1)'s `--baseline` merge flag.
2777
2778 fsl_ckout_merge() will fail if this is >0 and it does not refer
2779 to a checkin version or if this->mergeType is
2780 FSL_MERGE_TYPE_CHERRYPICK.
2781 */
2783 /**
2784 Specifies the merge type to perform. Certain merge-internal logic
2785 may override this. Specifically, integrate-merges may be treated
2786 as regular merges, as documented for FSL_MERGE_TYPE_INTEGRATE.
2787 */
2789 /**
2790 Gets called once per merge-updated file, passed a fsl_ckup_state
2791 instance with information about the merged file and related
2792 metadata. May be NULL, in which case the merge process will do as
2793 much work as it can, even if that means doing certain
2794 questionable things (such as skipping updates of binary files or
2795 symlinks because it refuses to merge them). As a rule of thumb,
2796 if fossil(1) performs a given "questional" merge features without
2797 generating an error, fsl_ckout_merge() does as well. This
2798 callback gives clients a chance to decide that certain states
2799 _Simply Will Not Stand_ and cancel the merge by returning non-0
2800 (preferably after calling fsl_cx_err_set() on the passed-in
2801 fsl_merge_state::f object).
2802
2803 The callback is called after any on-disk changes are made to
2804 the file, e.g. merging, file permissions, renaming, etc. However,
2805 when this->dryRun is true, filesystem-level changes are skipped.
2806 */
2808 /**
2809 Client-defined state for use with this->callback.
2810 */
2812 /**
2813 A hint to fsl_ckout_merge() about whether it needs to scan the
2814 checkout for changes. Set this to false ONLY if the calling code
2815 calls fsl_ckout_changes_scan() (or equivalent,
2816 e.g. fsl_vfile_changes_scan()) immediately before calling
2817 fsl_ckout_merge(), as that function requires a non-stale changes
2818 scan in order to function properly.
2819 */
2821 /**
2822 If true, the extraction process will "go through the motions" but
2823 will not write any files to disk. It may still perform I/O such
2824 as stat()'ing to see, e.g., if it would have needed to overwrite
2825 a file. When in dry-run, this->callback is still called as if
2826 dry-run mode were not in effect. Thus the on-disk state may not
2827 actually reflect what the callback sees when dry-run mode is
2828 active.
2829 */
2831 /**
2832 This flag is not part of the public API and will be removed
2833 once the merge operation's development has settled down.
2834 */
2835 unsigned short debug;
2836 /**
2837 TODO:
2838
2839 - How to handle fossil's --binary GLOBPATTERN flag. Plain string
2840 or a glob list object or a stateful predicate function or... ?
2841
2842 We currently rely entirely on the global `binary-glob` setting.
2843 */
2844};
2845/** Initialized-with-defaults fsl_merge_opt structure, intended for
2846 const-copy initialization. */
2847#define fsl_merge_opt_empty_m \
2848 {-1/*mergeRid*/,0/*baselineRid*/, \
2849 FSL_MERGE_TYPE_NORMAL/*mergeType*/, \
2850 NULL/*callback*/, NULL/*callbackState*/, \
2851 true/*scanForChanges*/, \
2852 false/*dryRun*/,0/*debug*/}
2853/** Initialized-with-defaults fsl_merge_opt structure, intended for
2854 non-const copy initialization. */
2856
2857/**
2858 UNDER CONSTRUCTION and not yet well-tested.
2859
2860 Performs a "merge" operation on the current checkout, merging in
2861 version opt->mergeRid. If that version has already been merged,
2862 this call has no SCM-related side effects.
2863
2864 Returns 0 on success, any number of non-0 codes on error,
2865 including, _but not limited to_:
2866
2867 - FSL_RC_NOT_A_CKOUT if f has no opened checkout.
2868
2869 - FSL_RC_OOM on allocation error.
2870
2871 - FSL_RC_TYPE if opt->mergeRid or opt->baselineRid do to refer to
2872 a checkin.
2873
2874 - FSL_RC_PHANTOM if a file participating in the merge is
2875 a phantom.
2876
2877 - FSL_RC_RANGE if the to-be-merged-in RID is the same as the
2878 current checkout RID or the same as the pivot/baseline of
2879 the merge.
2880
2881 - FSL_RC_NOT_FOUND if no common ancestor can be found for use as a
2882 basis for the merge.
2883
2884 - FSL_RC_MISUSE if the current checkout is empty (has an RID of 0).
2885
2886 - Any number of DB- or I/O-related codes, as well as codes from
2887 underlying APIs such as fsl_vfile_changes_scan().
2888
2889 For all but the most trivial argument validation errors or
2890 allocation errors, f's error state will be updated with a
2891 description of the problem.
2892
2893 TODOs and potential TODOs:
2894
2895 - There are certain illegal combinations of merge state which may
2896 require adding new result codes for. e.g. a no-op merge.
2897
2898 - Empty directories may be left behind when a merge removes all
2899 files in a directory. fsl_ckout_update() handles that case but
2900 fsl_ckout_merge() currently does not.
2901
2902*/
2903FSL_EXPORT int fsl_ckout_merge(fsl_cx * const f, fsl_merge_opt const * const opt);
2904
2905/**
2906 If zDirName is a directory name which contains what appears to
2907 be a fossil checkout database (noting that only a cursory check is done - the
2908 db is not opened and validated), the name of that database file (minus
2909 the directory part) is returned, else NULL is returned. The returned bytes
2910 are static.
2911
2912 @see fsl_ckout_dbnames()
2913*/
2914FSL_EXPORT char const * fsl_is_top_of_ckout(char const *zDirName);
2915
2916/**
2917 Returns an array of strings with the base names of valid fossil checkout
2918 databases. The array is terminated by a NULL element.
2919
2920 As of this writing, and for the foreseeable future, the list is
2921 comprised of only 3 elements, {".fslckout", "_FOSSIL_", NULL}, but
2922 the order of the non-NULL elements is unspecified by the interface.
2923*/
2924FSL_EXPORT char const ** fsl_ckout_dbnames(void);
2925
2926/** Convenience typedef. */
2928/**
2929 Callback type for use with fsl_ckout_rename(). It gets called once per
2930 iteration of a rename operation, along with the original options object
2931 for the rename and:
2932
2933 - zSrcName is the checkout-relative original name of the file.
2934 - zDestname is the checkout-relative new name of the file.
2935
2936 Both strings are owned by the calling operation and will be freed
2937 soon after this call returns. If the client needs them, they must
2938 make copies.
2939
2940 It must returns 0 on success. If it returns non-0 then the current
2941 renaming op is cancelled (rolled back) and the result code is
2942 propagated back to the caller of fsl_ckout_rename().
2943
2944 This gets called immediately after the associated db record is
2945 modified and before the filesystem move (if any) is performed.
2946
2947 Design note: ideally the callback would be called after the
2948 filesystem move, but the way the moves are currently processed (as
2949 a batch after the db updates, noting that those updates may trigger
2950 variou error conditions) precludes that. Alternately, we could
2951 delay the callback until the file-move phase (noting that the
2952 file-move step is optional), and that might be a sensible change to
2953 make.
2954*/
2956 char const * zSrcName, char const *zDestName);
2957
2958/**
2959 Options object for use with fsl_ckout_rename().
2960*/
2962 /**
2963 The source filename(s) or directory name(s) to rename. The
2964 contents of this list _must not_ be modified while
2965 fsl_ckout_rename() is running (e.g. via a callback function).
2966 */
2967 fsl_list const * src;
2968 /**
2969 The target filename or directory name to rename to.
2970 */
2971 char const * dest;
2972 /**
2973 If true, src and dest are resolved/normalized based on the current
2974 working directory, else they must be relative to the top of the
2975 checkout.
2976 */
2978 /**
2979 If true fsl_ckout_rename() will attempt to move files within the
2980 filesystem. If false, it will only do the db-side renaming.
2981 */
2983 /**
2984 If true, fsl_ckout_rename() will not perform any lasting
2985 operations but will "go through the motions" with the exception
2986 of actually attempting to move files on disk (if doFsMv is
2987 true). It will still report errors in this mode, with the
2988 exception that filesystem-level moving is not attempted so
2989 potential failures there cannot be detected.
2990
2991 Achtung: in dry-run mode it will trigger a rollback of any
2992 pending transaction which is opened before fsl_ckout_rename() is
2993 called.
2994 */
2996 /** Optional callback. May be NULL. */
2998 /** Optional state for the callback. */
3000};
3001
3002/** Initialized-with-defaults fsl_ckout_rename_opt structure, intended for
3003 const-copy initialization. */
3004#define fsl_ckout_rename_opt_empty_m {NULL,NULL,true,false,false,NULL,NULL}
3005
3006/** Initialized-with-defaults fsl_ckout_rename_opt structure, intended for
3007 non-const copy initialization. */
3009
3010/**
3011 This routine renames one or more SCM-managed files matching all
3012 entries in opt->src to opt->dest within the current checkout. This
3013 updates the current checkout's vfile table with the changes, and
3014 optionally attempts to move the files within the filesystem, but
3015 does not commit anything, so the change may still be reverted later
3016 on.
3017
3018 If an entry in opt->src matches an existing directory name within
3019 the SCM-managed file list, this function assumes that all files
3020 under that directory are to be moved.
3021
3022 If opt->relativeToCwd is true then the destination name and all
3023 opt->src names are canonicalized based on the current working
3024 directory (see fsl_getcwd()), otherwise they are assumed to be
3025 relative to f's current checkout directory.
3026
3027 If opt->dest refers to an _existing_ directory, when an opt->src
3028 entry refers to a directory then that whole directory, including the
3029 directory name part, is renamed. If opt->dest does not exist in the
3030 filesystem and if opt->src resolves to multiple inputs, opt->dest is
3031 assumed to be a new target directory but the renaming behavior of
3032 the opt->src files differs. Examples:
3033
3034 - Case 1: opt->dest refers to an existing directory: moving
3035 directory foo/bar to baz will result in baz/bar.
3036
3037 - Case 2: opt->dest does not refer to an existing directory: moving
3038 directory foo/bar to baz results in baz with the previous contents
3039 of foo/bar.
3040
3041 Why? Because that's how fossil(1) does it.
3042
3043 This function matches opt->src entries only against
3044 `vfile.pathname`, not `vfile.origname`.
3045
3046 If opt->doFsMv is true then the final operation this function
3047 attempts is to rename source files to their new destination. It
3048 will only attempt this in cases where (A) the original file exists
3049 and (B) the destination file does _not_ exist. Any errors generated
3050 during this filesystem-level rename/move step _are ignored_ for two
3051 reasons: 1) fossil(1) does it that way and (2) after moving any
3052 files, trying to roll back and undo the filesystem-level operations
3053 would add a significant amount of complexity and new errror cases
3054 (what happens when a try-to-undo-rename fails?).
3055
3056 Returns 0 on succcess. Potential errors include:
3057
3058 - FSL_RC_OOM on allocation error.
3059
3060 - FSL_RC_NOT_A_CKOUT if f has no opened checkout.
3061
3062 - FSL_RC_MISUSE: opt->src contains multiple entries but the
3063 destination is not an _existing_ directory.
3064
3065 - FSL_RC_ALREADY_EXISTS: cannot rename because the destination name
3066 is already in use by another record.
3067
3068 - FSL_RC_TYPE: opt->dest refers to a non-directory and an opt->src
3069 entry refers to a directory.
3070
3071 - Any potential DB-related errors.
3072
3073 BUGS/Shortcomings:
3074
3075 - If it fails moving files in the filesystem, it might have
3076 successfully already moved one or more source files, and those
3077 moves are not undone.
3078
3079 - Depending on the case-sensitivity of the repo and the filesystem,
3080 it might (UNTESTED) fail to rename a file if the new name differs
3081 only in its case (e.g. `README.TXT` to `README.txt`). Those
3082 relavant code renames such vfile entries but leaves the filesystem
3083 entries intact because fossil(1) does it that way.
3084
3085 - If it moves a whole directory full of files it leaves any
3086 original directories intact. Improving this is on the TODO list.
3087 Often, such directories have contents (e.g. compiled/generated/temp
3088 files) and cannot be removed.
3089*/
3091 fsl_ckout_rename_opt const * opt);
3092
3093/**
3094 Undoes a rename scheduled by fsl_ckout_rename(). zNewName is the
3095 current (renamed) name of the file.
3096
3097 If relativeToCwd is true then zNewName is canonicalized based on
3098 the current working directory (see fsl_getcwd()), otherwise it is
3099 assumed to be relative to f's current checkout directory.
3100
3101 On success, or if no such pending rename is found, it returns 0.
3102 If it actually performs a db-level rename then it sets
3103 `*didSomething` to true if didSomething is not NULL. It should
3104 arguably return FSL_RC_NOT_FOUND (or some such) if no matching
3105 rename is pending, but that currently feels overly-pedantic.
3106
3107 If doFsMv is true and a db entry is renamed and a file with the
3108 new name exists in the filesystem then this function will
3109 _delete_ any file which has the original name and rename the zNewName
3110 file to its reverted name. If that fails, the operation as a
3111 whole will fail and the db changes will be rolled back. Note,
3112 however, that a file deleted by this operation cannot be recovered
3113 and that the deletion must be done before the rename is attempted.
3114
3115 On error, returns any of a wide array of non-0 result codes, only
3116 two of which can come directly from this function: FSL_RC_OOM or
3117 FSL_RC_NOT_A_CKOUT. Any other non-zero result codes are propagated
3118 errors from lower-level code.
3119*/
3121 char const * zNewName,
3122 bool relativeToCwd, bool doFsMv,
3123 bool *didSomething);
3124
3125/**
3126 Fetches the vfile.pathname value for the given vfile.id
3127 entry. Results are undefined if f does not have an opened
3128 checkout. On success returns 0 and sets `*zOut` to the name,
3129 transfering ownership to the caller (who must eventually pass it
3130 to fsl_free()). If absolute is true then the returned name has the
3131 checkout dir prepended to it, else it is relative to the top of
3132 the repo.
3133
3134 Potential TODO: this routine is in no way optimized for heavy use
3135 within an app, expecting to be only rarely used, e.g. in
3136 conjunction with fsl_ckout_rename()-like ops. If it sees any
3137 significant use it should be refactored to use a cached statement.
3138*/
3140 bool absolute, char **zOut);
3141
3142
3143#if defined(__cplusplus)
3144} /*extern "C"*/
3145#endif
3146#endif
3147/* ORG_FOSSIL_SCM_FSL_CHECKOUT_H_INCLUDED */
FSL_EXPORT int fsl_ckout_fingerprint_check(fsl_cx *const f)
Performs a "fingerprint check" between f's current checkout and repository databases.
FSL_EXPORT int fsl_filename_to_vfile_id(fsl_cx *const f, fsl_id_t vid, char const *zName, fsl_id_t *const vfid)
Expects f to have an opened checkout and zName to be the name of an entry in the vfile table where vf...
int(* fsl_ckout_changes_f)(void *state, fsl_ckout_change_e change, char const *filename, char const *origName)
A typedef for visitors of checkout status information via fsl_ckout_changes_visit().
Definition checkout.h:691
FSL_EXPORT int fsl_ckout_rename_revert(fsl_cx *const f, char const *zNewName, bool relativeToCwd, bool doFsMv, bool *didSomething)
Undoes a rename scheduled by fsl_ckout_rename().
FSL_EXPORT bool fsl_checkin_is_enqueued(fsl_cx *const f, char const *zName, bool relativeToCwd)
Returns true if the file named by zName is in f's current file checkin queue.
fsl_ckup_fchange_e
This enum lists the various types of individual file change states which can happen during a checkout...
Definition checkout.h:1584
@ FSL_CKUP_FCHANGE_INVALID
Sentinel value.
Definition checkout.h:1586
@ FSL_CKUP_FCHANGE_CONFLICT_MERGED
Special case of FSL_CKUP_FCHANGE_MERGED.
Definition checkout.h:1629
@ FSL_CKUP_FCHANGE_RENAMED
File was renamed in the updated-to version.
Definition checkout.h:1665
@ FSL_CKUP_FCHANGE_CONFLICT_RM
Edited locally but removed from updated-to version.
Definition checkout.h:1645
@ FSL_CKUP_FCHANGE_RM
Removed from SCM in the updated-to to version OR in the checked-out version but not yet committed.
Definition checkout.h:1607
@ FSL_CKUP_FCHANGE_MERGED
Updated with a merge by the update process.
Definition checkout.h:1622
@ FSL_CKUP_FCHANGE_CONFLICT_BINARY
Indicates that a merge of binary content was requested.
Definition checkout.h:1661
@ FSL_CKUP_FCHANGE_CONFLICT_ADDED
Added in the current checkout but also contained in the updated-to version.
Definition checkout.h:1633
@ FSL_CKUP_FCHANGE_RM_PROPAGATED
Removed from the checked-out version but not yet commited, so was carried over to the updated-to vers...
Definition checkout.h:1612
@ FSL_CKUP_FCHANGE_ADD_PROPAGATED
Added to SCM in the current checkout version and carried over into the updated-to version.
Definition checkout.h:1600
@ FSL_CKUP_FCHANGE_UPDATED
Updated or replaced without a merge by the checkout/update process.
Definition checkout.h:1615
@ FSL_CKUP_FCHANGE_ADDED
Added to SCM in the updated-to version.
Definition checkout.h:1595
@ FSL_CKUP_FCHANGE_EDITED
Locally modified.
Definition checkout.h:1668
@ FSL_CKUP_FCHANGE_CONFLICT_ADDED_UNMANAGED
Added by the updated-to version but a local unmanaged copy exists.
Definition checkout.h:1642
@ FSL_CKUP_FCHANGE_CONFLICT_SYMLINK
Cannot merge if one or both of the update/updating verions of a file is a symlink.
Definition checkout.h:1652
@ FSL_CKUP_FCHANGE_UPDATED_BINARY
Merge was not performed because at least one of the inputs appears to be binary.
Definition checkout.h:1620
@ FSL_CKUP_FCHANGE_NONE
Was unchanged between the previous and updated-to version, so no change was made to the on-disk file.
Definition checkout.h:1591
FSL_EXPORT int fsl_ckout_changes_scan(fsl_cx *f)
This is equivalent to calling fsl_vfile_changes_scan() with the arguments (f, -1, 0).
FSL_EXPORT int fsl_ckout_manifest_write(fsl_cx *const f, int manifest, int manifestUuid, int manifestTags, int *const wroteWhat)
Might write out the files manifest, manifest.uuid, and/or manifest.tags for the current checkout to t...
const fsl_merge_opt fsl_merge_opt_empty
Initialized-with-defaults fsl_merge_opt structure, intended for non-const copy initialization.
FSL_EXPORT int fsl_checkin_T_add2(fsl_cx *f, fsl_card_T *t)
Works identically to fsl_checkin_T_add() except that it takes its argument in the form of a T-card ob...
FSL_EXPORT char const * fsl_is_top_of_ckout(char const *zDirName)
If zDirName is a directory name which contains what appears to be a fossil checkout database (noting ...
FSL_EXPORT void fsl_ckout_manifest_setting(fsl_cx *f, int *m)
Returns a bitmask representing which manifest files, if any, will be written when opening or updating...
fsl_ckup_rm_state_e
State values for use with fsl_ckup_state::fileRmInfo.
Definition checkout.h:1441
@ FSL_CKUP_RM_KEPT
Indicates that a file was removed from a checkout but kept in the filesystem because it was locally m...
Definition checkout.h:1452
@ FSL_CKUP_RM_NOT
Indicates that the file was not removed in a given checkout.
Definition checkout.h:1447
@ FSL_CKUP_RM
Indicates that a file was removed from a checkout and the filesystem, with the caveat that failed att...
Definition checkout.h:1459
FSL_EXPORT bool fsl_is_rooted_in_ckout(fsl_cx *const f, char const *const zAbsPath)
Returns true if f has an opened checkout and the given absolute path is rooted in that checkout,...
FSL_EXPORT int fsl_ckout_vfile_ids(fsl_cx *const f, fsl_id_t vid, fsl_id_bag *const dest, char const *zName, bool relativeToCwd, bool changedOnly)
This is a variant of fsl_filename_to_vfile_ids() which accepts filenames in a more flexible form than...
FSL_EXPORT int fsl_card_F_ckout_mtime(fsl_cx *const f, fsl_id_t vid, fsl_card_F const *const fc, fsl_time_t *const repoMtime, fsl_time_t *const localMtime)
Fetches the timestamp of the given F-card's name against the filesystem and/or the most recent checki...
FSL_EXPORT int fsl_ckout_unmanage(fsl_cx *f, fsl_ckout_unmanage_opt const *opt)
The converse of fsl_ckout_manage(), this queues a file for removal from the current checkout.
FSL_EXPORT int fsl_ckout_changes_visit(fsl_cx *f, fsl_id_t vid, bool doChangeScan, fsl_ckout_changes_f visitor, void *state)
Compares the changes of f's local checkout against repository version vid (checkout version if vid is...
int(* fsl_ckout_revert_f)(char const *zFilename, fsl_ckout_revert_e changeType, void *callbackState)
Callback type for use with fsl_ckout_revert().
Definition checkout.h:2165
FSL_EXPORT int fsl_ckout_manage(fsl_cx *const f, fsl_ckout_manage_opt *const opt)
Adds the given filename or directory (recursively) to the current checkout vfile list of files as a t...
FSL_EXPORT int fsl_ckout_merge(fsl_cx *const f, fsl_merge_opt const *const opt)
UNDER CONSTRUCTION and not yet well-tested.
FSL_EXPORT int fsl_is_rooted_in_ckout2(fsl_cx *const f, char const *const zAbsPath)
Works like fsl_is_rooted_in_ckout() except that it returns 0 on success, and on error updates f with ...
FSL_EXPORT int fsl_ckout_calc_update_version(fsl_cx *f, fsl_id_t *outRid)
Tries to calculate a version to update the current checkout version to, preferring the tip of the cur...
FSL_EXPORT const fsl_ckout_manage_opt fsl_ckout_manage_opt_empty
Initialized-with-defaults fsl_ckout_manage_opt instance, intended for use in non-const copy initializ...
Definition checkout.h:354
fsl_ckout_revert_e
Change-type values for use with fsl_ckout_revert_f() callbacks.
Definition checkout.h:2115
@ FSL_REVERT_NONE
Sentinel value.
Definition checkout.h:2117
@ FSL_REVERT_REMOVE
File was previously queued for removal but unqueued by the revert process.
Definition checkout.h:2129
@ FSL_REVERT_PERMISSIONS
File's permissions (only) were reverted.
Definition checkout.h:2143
@ FSL_REVERT_CONTENTS
File's contents reverted.
Definition checkout.h:2150
@ FSL_REVERT_RENAME
File was previously scheduled to be renamed, but the rename was reverted.
Definition checkout.h:2141
@ FSL_REVERT_UNMANAGE
File was previously queued for addition but unqueued by the revert process.
Definition checkout.h:2122
fsl_file_overwrite_policy_e
File-overwrite policy values for use with fsl_ckup_opt and friends.
Definition checkout.h:1422
@ FSL_OVERWRITE_NEVER
Indicates that files should never be overwritten, and silently skipped over.
Definition checkout.h:1434
@ FSL_OVERWRITE_ERROR
Indicates that an error should be triggered if a file would be overwritten.
Definition checkout.h:1425
@ FSL_OVERWRITE_ALWAYS
Indicates that files should always be overwritten.
Definition checkout.h:1429
fsl_ckout_change_e
Change-type flags for use with fsl_ckout_changes_visit() and friends.
Definition checkout.h:600
@ FSL_CKOUT_CHANGE_REMOVED
Indicates that a file was removed from SCM management.
Definition checkout.h:653
@ FSL_CKOUT_CHANGE_BECAME_SYMLINK
Indicates that the file has changed to a symlink.
Definition checkout.h:635
@ FSL_CKOUT_CHANGE_INTEGRATE_ADD
Indicates that a file was added as the result of an integrate-merge.
Definition checkout.h:626
@ FSL_CKOUT_CHANGE_MOD
Indicates that a file was modified in some unspecified way.
Definition checkout.h:608
@ FSL_CKOUT_CHANGE_MERGE_ADD
Indicates that a file was added as the result of a merge.
Definition checkout.h:616
@ FSL_CKOUT_CHANGE_NONE
Sentinel placeholder value.
Definition checkout.h:604
@ FSL_CKOUT_CHANGE_ADDED
Indicates that a file was added.
Definition checkout.h:649
@ FSL_CKOUT_CHANGE_INTEGRATE_MOD
Indicates that a file was modified as the result of an integrate-merge.
Definition checkout.h:621
@ FSL_CKOUT_CHANGE_MISSING
Indicates that a file is missing from the local checkout.
Definition checkout.h:657
@ FSL_CKOUT_CHANGE_NOT_EXEC
Indicates that the file lost the is-executable trait but is otherwise unmodified.
Definition checkout.h:640
@ FSL_CKOUT_CHANGE_NOT_SYMLINK
Indicates that the file was previously a symlink but is now a plain file.
Definition checkout.h:645
@ FSL_CKOUT_CHANGE_RENAMED
Indicates that a file was renamed.
Definition checkout.h:661
@ FSL_CKOUT_CHANGE_IS_EXEC
Indicates that the file gained the is-executable trait but is otherwise unmodified.
Definition checkout.h:631
@ FSL_CKOUT_CHANGE_MERGE_MOD
Indicates that a file was modified as the result of a merge.
Definition checkout.h:612
int(* fsl_merge_f)(fsl_merge_state const *const)
Callback type for use with fsl_merge_opt and fsl_ckout_merge().
Definition checkout.h:2720
fsl_ckout_sig_e
A bitmask of flags for fsl_vfile_changes_scan().
Definition checkout.h:720
@ FSL_VFILE_CKSIG_KEEP_OTHERS
Indicates that when populating the vfile table, it should be not be cleared of entries for other chec...
Definition checkout.h:749
@ FSL_VFILE_CKSIG_SETMTIME
For unchanged or changed-by-merge files, set the mtime to last check-out time, as determined by fsl_m...
Definition checkout.h:739
@ FSL_VFILE_CKSIG_ENOTFILE
Non-file/non-link FS objects trigger an error.
Definition checkout.h:729
@ FSL_VFILE_CKSIG_WRITE_CKOUT_VERSION
If set and fsl_vfile_changes_scan() is passed a version other than the pre-call checkout version,...
Definition checkout.h:759
@ FSL_VFILE_CKSIG_NONE
The empty flags set.
Definition checkout.h:724
@ FSL_VFILE_CKSIG_HASH
Verify file content using hashing, regardless of whether or not file timestamps differ.
Definition checkout.h:734
FSL_EXPORT int fsl_checkin_commit(fsl_cx *f, fsl_checkin_opt const *opt, fsl_id_t *newRid, fsl_uuid_str *newUuid)
This creates and saves a "checkin manifest" for the current checkout.
fsl_vfile_change_e
Hard-coded range of values of the vfile.chnged db field.
Definition checkout.h:568
@ FSL_VFILE_CHANGE_IS_EXEC
File became executable but has unmodified contents.
Definition checkout.h:582
@ FSL_VFILE_CHANGE_MERGE_MOD
File changed due to a merge.
Definition checkout.h:574
@ FSL_VFILE_CHANGE_NOT_SYMLINK
File lost symlink status and has contents equal to its old target.
Definition checkout.h:588
@ FSL_VFILE_CHANGE_BECAME_SYMLINK
File became a symlink whose target equals its old contents.
Definition checkout.h:584
@ FSL_VFILE_CHANGE_NOT_EXEC
File lost executable status but has unmodified contents.
Definition checkout.h:586
@ FSL_VFILE_CHANGE_MOD
File edit.
Definition checkout.h:572
@ FSL_VFILE_CHANGE_INTEGRATE_MOD
File changed due to an integrate merge.
Definition checkout.h:578
@ FSL_VFILE_CHANGE_MERGE_ADD
File added by a merge.
Definition checkout.h:576
@ FSL_VFILE_CHANGE_NONE
File is unchanged.
Definition checkout.h:570
@ FSL_VFILE_CHANGE_INTEGRATE_ADD
File added by an integrate merge.
Definition checkout.h:580
FSL_EXPORT int fsl_vfile_unload(fsl_cx *const f, fsl_id_t vid)
Clears out all entries in the current checkout's vfile table with the given vfile....
FSL_EXPORT int fsl_ckout_file_content(fsl_cx *const f, bool relativeToCwd, char const *zName, fsl_buffer *const dest)
Looks for the given file in f's current checkout.
FSL_EXPORT const fsl_ckout_revert_opt fsl_ckout_revert_opt_empty
Initialized-with-defaults fsl_ckout_revert_opt instance, intended for use in non-const copy initializ...
Definition checkout.h:2222
FSL_EXPORT int fsl_vfile_load(fsl_cx *const f, fsl_id_t manifestRid, bool clearOtherVersions, uint32_t *missingCount)
This "mostly internal" routine (re)populates f's checkout vfile table with all files from the given c...
FSL_EXPORT const fsl_repo_open_ckout_opt fsl_repo_open_ckout_opt_empty
Empty-initialised fsl_repo_open_ckout_opt instance.
Definition checkout.h:1533
FSL_EXPORT int fsl_repo_open_ckout(fsl_cx *const f, fsl_repo_open_ckout_opt const *opt)
Opens a checkout db for use with the currently-connected repository or creates a new checkout db.
int(* fsl_ckout_unmanage_f)(fsl_ckout_unmanage_state const *ums)
Callback type for use with fsl_ckout_unmanage().
Definition checkout.h:460
FSL_EXPORT char const * fsl_preferred_ckout_db_name(void)
Returns the base name of the current platform's checkout database file.
int(* fsl_checkin_queue_f)(const char *filename, void *state)
Callback type for use with fsl_checkin_queue_opt for alerting a client about exactly which files get ...
Definition checkout.h:816
FSL_EXPORT int fsl_ckout_rename(fsl_cx *const f, fsl_ckout_rename_opt const *opt)
This routine renames one or more SCM-managed files matching all entries in opt->src to opt->dest with...
FSL_EXPORT int fsl_checkin_dequeue(fsl_cx *const f, fsl_checkin_queue_opt const *opt)
The opposite of fsl_checkin_enqueue(), this opt->filename, which may resolve to a single name or a di...
const fsl_ckout_rename_opt fsl_ckout_rename_opt_empty
Initialized-with-defaults fsl_ckout_rename_opt structure, intended for non-const copy initialization.
fsl_merge_type_e
Merge type enum for use with fsl_merge_opt::mergeType.
Definition checkout.h:2729
@ FSL_MERGE_TYPE_INTEGRATE
Indicates an "integrate" merge, which tells the next checkin operation to apply a "closed" tag to the...
Definition checkout.h:2745
@ FSL_MERGE_TYPE_BACKOUT
Indicates a backout merge, a reverse cherrypick, backing out any changes which were added by the corr...
Definition checkout.h:2756
@ FSL_MERGE_TYPE_CHERRYPICK
Indicates a cherrypick merge, pulling in only the changes made to a specific checkin without otherwis...
Definition checkout.h:2750
@ FSL_MERGE_TYPE_NORMAL
Indicates a normal merge.
Definition checkout.h:2733
FSL_EXPORT int fsl_ckout_db_search(char const *dirName, bool checkParentDirs, fsl_buffer *const pOut)
Searches the given directory (or the current directory if dirName is 0) for a fossil checkout databas...
FSL_EXPORT int fsl_checkin_enqueue(fsl_cx *f, fsl_checkin_queue_opt const *opt)
Adds one or more files to f's list of "selected" files - those which should be included in the next c...
FSL_EXPORT bool fsl_ckout_has_changes(fsl_cx *const f)
If f has an opened checkout which has local changes noted in its checkout db state (the vfile table),...
FSL_EXPORT int fsl_filename_to_vfile_ids(fsl_cx *const f, fsl_id_t vid, fsl_id_bag *const dest, char const *zName, bool changedOnly)
Searches the vfile table where vfile.vid=vid for a name which matches zName or all vfile entries foun...
int(* fsl_ckout_rename_f)(fsl_cx *, fsl_ckout_rename_opt const *, char const *zSrcName, char const *zDestName)
Callback type for use with fsl_ckout_rename().
Definition checkout.h:2955
fsl_cx_manifest_mask_e
Bitmask used by fsl_ckout_manifest_setting() and fsl_ckout_manifest_write().
Definition checkout.h:1995
@ FSL_MANIFEST_UUID
Coresponds to the file "manifest.uuid".
Definition checkout.h:1999
@ FSL_MANIFEST_MAIN
Coresponds to the file "manifest".
Definition checkout.h:1997
@ FSL_MANIFEST_TAGS
Coresponds to the file "manifest.tags".
Definition checkout.h:2001
const fsl_checkin_queue_opt fsl_checkin_queue_opt_empty
Initialized-with-defaults fsl_checkin_queue_opt structure, intended for non-const copy initialization...
int(* fsl_ckout_manage_f)(fsl_ckout_manage_state const *mst, bool *include)
Callback type for use with fsl_ckout_manage_opt().
Definition checkout.h:246
fsl_merge_fchange_e
File change types for use with fsl_merge_state::fileChangeType.
Definition checkout.h:2549
@ FSL_MERGE_FCHANGE_COPIED
File content was copied as-is from (M) to (V).
Definition checkout.h:2564
@ FSL_MERGE_FCHANGE_CONFLICT_ADDED_UNMANAGED
Added to (V) by (M) but a local unmanaged copy exists.
Definition checkout.h:2593
@ FSL_MERGE_FCHANGE_CONFLICT_SYMLINK
Cannot merge if one or both of the update/updating versions of a file is a symlink.
Definition checkout.h:2620
@ FSL_MERGE_FCHANGE_RENAMED
File was renamed in the updated-to version.
Definition checkout.h:2636
@ FSL_MERGE_FCHANGE_RM
File was removed from (V) via (M).
Definition checkout.h:2568
@ FSL_MERGE_FCHANGE_ADDED
File was added to (V) from (M).
Definition checkout.h:2560
@ FSL_MERGE_FCHANGE_NONE
Not currently used.
Definition checkout.h:2556
@ FSL_MERGE_FCHANGE_CONFLICT_MERGED
Special case of FSL_MERGE_FCHANGE_MERGED.
Definition checkout.h:2580
@ FSL_MERGE_FCHANGE_CONFLICT_BINARY
Indicates that a merge of binary content was requested.
Definition checkout.h:2629
@ FSL_MERGE_FCHANGE_MERGED
Content from (M) was merged into (V).
Definition checkout.h:2572
@ FSL_MERGE_FCHANGE_count
This is the number of entries in this enum, for purposes of creating, e.g.
Definition checkout.h:2642
FSL_EXPORT int fsl_vfile_changes_scan(fsl_cx *const f, fsl_id_t vid, unsigned cksigFlags)
This function populates (if needed) the vfile table of f's checkout db for the given checkin version ...
FSL_EXPORT int fsl_ckout_filename_check(fsl_cx *const f, bool relativeToCwd, char const *zOrigName, fsl_buffer *const pOut)
Given a fsl_cx with an opened checkout, and a file/directory name, this function canonicalizes zOrigN...
FSL_EXPORT const fsl_checkin_opt fsl_checkin_opt_empty
Empty-initialized fsl_checkin_opt instance, intended for use in copy-constructing.
Definition checkout.h:1283
FSL_EXPORT int fsl_repo_ckout(fsl_cx *f, fsl_ckup_opt const *cOpt)
A fsl_repo_extract() proxy which extracts the contents of the repository version specified by opt->ch...
FSL_EXPORT const fsl_ckout_unmanage_opt fsl_ckout_unmanage_opt_empty
Initialized-with-defaults fsl_ckout_unmanage_opt instance, intended for use in non-const copy initial...
Definition checkout.h:525
FSL_EXPORT int fsl_ckout_revert(fsl_cx *const f, fsl_ckout_revert_opt const *opt)
Reverts changes to checked-out files, replacing their on-disk versions with the current checkout's ve...
FSL_EXPORT int fsl_vfile_unload_except(fsl_cx *const f, fsl_id_t vid)
A counterpart of fsl_vfile_unload() which removes all vfile entries where vfile.vid is not the given ...
FSL_EXPORT int fsl_checkin_T_add(fsl_cx *f, fsl_tagtype_e tagType, fsl_uuid_cstr uuid, char const *name, char const *value)
Works like fsl_deck_T_add(), adding the given tag information to the pending checkin state.
FSL_EXPORT int fsl_ckout_clear_db(fsl_cx *f)
Clears all contents from f's checkout database, including the vfile table, vmerge table,...
FSL_EXPORT void fsl_checkin_discard(fsl_cx *const f)
Discards any state accumulated for a pending checking, including any files queued via fsl_checkin_enq...
FSL_EXPORT char const ** fsl_ckout_dbnames(void)
Returns an array of strings with the base names of valid fossil checkout databases.
int(* fsl_ckup_f)(fsl_ckup_state const *cState)
A callback type for use with fsl_ckup_state.
Definition checkout.h:1578
FSL_EXPORT void fsl_ckout_version_info(fsl_cx *const f, fsl_id_t *const rid, fsl_uuid_cstr *const uuid)
Returns version information for the current checkout.
FSL_EXPORT int fsl_vfile_pathname(fsl_cx *const f, fsl_id_t vfid, bool absolute, char **zOut)
Fetches the vfile.pathname value for the given vfile.id entry.
FSL_EXPORT int fsl_ckout_open_dir(fsl_cx *const f, char const *dirName, bool checkParentDirs)
Tries to open a checked-out fossil repository db in the given directory (or "." if dirName is NULL).
FSL_EXPORT int fsl_ckout_update(fsl_cx *f, fsl_ckup_opt const *opt)
UNDER CONSTRUCTION.
FSL_EXPORT const fsl_ckup_opt fsl_ckup_opt_empty
Empty-initialised fsl_ckup_opt instance.
Definition checkout.h:1867
int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
Definition config.h:271
int64_t fsl_time_t
The type used to represent type values.
Definition config.h:296
int64_t fsl_int_t
fsl_int_t is a signed integer type used to denote "relative" ranges and lengths, or to tell a routine...
Definition config.h:143
#define FSL_EXPORT
Definition config.h:66
repo.h declares APIs specifically dealing with repository-db-side state, as opposed to specifically c...
fsl_tagtype_e
Artifact tag types used by the Fossil framework.
Definition repo.h:107
A general-purpose buffer class, analog to Fossil's Blob class, but it is not called fsl_blob to avoid...
Definition util.h:684
F-cards each represent one file entry in a Manifest Artifact (i.e., a checkin version).
Definition repo.h:2200
Represents a tag in a Manifest or Control Artifact.
Definition repo.h:2278
Parameters for fsl_checkin_commit().
Definition checkout.h:1074
bool dryRun
If true, the checkin's db savepoint is rolled back after it's complete, effectively meaning that the ...
Definition checkout.h:1174
char const * closeBranch
If this is not NULL then the committed manifest will include a tag which closes the branch.
Definition checkout.h:1230
bool allowMergeConflict
If true, allow a file to be checked in if it contains fossil-style merge conflict markers,...
Definition checkout.h:1142
bool isPrivate
If true, the checkin will be marked as private, otherwise it will be marked as private or public,...
Definition checkout.h:1116
bool scanForChanges
A hint to fsl_checkin_commit() about whether it needs to scan the checkout for changes.
Definition checkout.h:1154
char const * bgColor
If this->branch is not NULL, this is applied as its "bgcolor" propagating property.
Definition checkout.h:1109
char const * messageMimeType
The optional mime type for the message.
Definition checkout.h:1085
double julianTime
Time of the checkin.
Definition checkout.h:1221
bool integrate
Tells the checkin to close merged-in branches (merge type of 0).
Definition checkout.h:1135
char const * message
The commit message.
Definition checkout.h:1079
bool calcRCard
Whether or not to calculate an R-card.
Definition checkout.h:1127
char const * branch
If not NULL, makes the checkin the start of a new branch with this name.
Definition checkout.h:1098
char const * user
The user name for the checkin.
Definition checkout.h:1092
char const * dumpManifestFile
Tells fsl_checkin_commit() to dump the generated manifest to this file.
Definition checkout.h:1237
int deltaPolicy
Whether to allow (or try to force) a delta manifest or not.
Definition checkout.h:1215
bool rmRemovedFiles
NOT YET IMPLEMENTED!
Definition checkout.h:1165
Options object type used by fsl_checkin_enqueue() and fsl_checkin_dequeue().
Definition checkout.h:822
void * callbackState
Opaque client-side state for use as the 2nd argument to this->callback.
Definition checkout.h:883
fsl_checkin_queue_f callback
It not NULL, is pass passed the checkout-relative filename of each enqueued/dequeued file and this->c...
Definition checkout.h:877
bool relativeToCwd
If true, filename (if not absolute) is interpreted as relative to the current working directory,...
Definition checkout.h:833
char const * filename
File or directory name to enqueue/dequeue to/from a pending checkin.
Definition checkout.h:827
bool onlyModifiedFiles
If true, only flagged-as-modified files will be enqueued by fsl_checkin_enqueue().
Definition checkout.h:870
fsl_id_bag const * vfileIds
If not NULL then this->filename and this->relativeToCwd are IGNORED and any to-queue filename(s) is/a...
Definition checkout.h:852
bool scanForChanges
If true, fsl_vfile_changes_scan() is called to ensure that the filesystem and vfile tables agree.
Definition checkout.h:862
Options for use with fsl_ckout_manage().
Definition checkout.h:251
void * callbackState
State to be passed to this->callback.
Definition checkout.h:308
fsl_ckout_manage_f callback
Optional predicate function which may be called for each to-be-added filename.
Definition checkout.h:303
bool checkIgnoreGlobs
Whether or not to check the name(s) against the 'ignore-globs' config setting (if set).
Definition checkout.h:281
uint32_t updated
Number of files which were requested to be added but were only updated because they had previously be...
Definition checkout.h:326
struct fsl_ckout_manage_opt::@165150144055323066204210121204355317235107070054 counts
These counts are updated by fsl_ckout_manage() to report what it did.
bool relativeToCwd
Whether to evaluate the given name as relative to the current working directory or to the current che...
Definition checkout.h:276
char const * filename
The file or directory name to add.
Definition checkout.h:264
uint32_t skipped
The number of files skipped over for addition.
Definition checkout.h:338
uint32_t added
Number of files actually added by fsl_ckout_manage().
Definition checkout.h:318
State passed to fsl_ckout_manage_f() callback.
Definition checkout.h:190
fsl_ckout_manage_opt const * opt
The options object passed to the corresponding call to fsl_ckout_manage().
Definition checkout.h:203
char const * filename
Definition checkout.h:220
fsl_cx * f
The fsl_cx instance for the correspnding fsl_ckout_manage() call.
Definition checkout.h:195
Options object for use with fsl_ckout_rename().
Definition checkout.h:2961
bool doFsMv
If true fsl_ckout_rename() will attempt to move files within the filesystem.
Definition checkout.h:2982
bool dryRun
If true, fsl_ckout_rename() will not perform any lasting operations but will "go through the motions"...
Definition checkout.h:2995
bool relativeToCwd
If true, src and dest are resolved/normalized based on the current working directory,...
Definition checkout.h:2977
char const * dest
The target filename or directory name to rename to.
Definition checkout.h:2971
fsl_ckout_rename_f callback
Optional callback.
Definition checkout.h:2997
void * callbackState
Optional state for the callback.
Definition checkout.h:2999
fsl_list const * src
The source filename(s) or directory name(s) to rename.
Definition checkout.h:2967
Options for passing to fsl_ckout_revert().
Definition checkout.h:2172
bool scanForChanges
If true, fsl_vfile_changes_scan() is called to ensure that the filesystem and vfile tables agree.
Definition checkout.h:2198
char const * filename
File or directory name to revert.
Definition checkout.h:2176
void * callbackState
State for this->callback.
Definition checkout.h:2207
fsl_id_bag const * vfileIds
An alternative to assigning this->filename is to point this->vfileIds to a bag of vfile....
Definition checkout.h:2184
bool relativeToCwd
Interpret filename as relative to cwd if true, else relative to the current checkout root.
Definition checkout.h:2190
fsl_ckout_revert_f callback
Optional callback to notify the client of what gets reverted.
Definition checkout.h:2203
Options for use with fsl_ckout_unmanage().
Definition checkout.h:465
void * callbackState
State to be passed to this->callback.
Definition checkout.h:510
bool relativeToCwd
Whether to evaluate this->filename as relative to the current working directory (true) or to the curr...
Definition checkout.h:491
fsl_ckout_unmanage_f callback
Optional predicate function which will be called after each file is made unmanaged.
Definition checkout.h:506
fsl_id_bag const * vfileIds
An alternative to assigning this->filename is to point this->vfileIds to a bag of vfile....
Definition checkout.h:478
char const * filename
The file or directory name to add.
Definition checkout.h:470
bool scanForChanges
If true, fsl_vfile_changes_scan() is called to ensure that the filesystem and vfile tables agree.
Definition checkout.h:499
State passed to fsl_ckout_unmanage_f() callback.
Definition checkout.h:408
fsl_cx * f
The fsl_cx instance for the correspnding fsl_ckout_unmanage() call.
Definition checkout.h:413
char const * filename
Definition checkout.h:438
fsl_ckout_unmanage_opt const * opt
The options object passed to the corresponding call to fsl_ckout_unmanage().
Definition checkout.h:421
Options for use with fsl_repo_ckout() and fsl_ckout_update().
Definition checkout.h:1774
bool scanForChanges
A hint to fsl_repo_ckout() and fsl_ckout_update() about whether it needs to scan the checkout for cha...
Definition checkout.h:1841
fsl_ckup_f callback
Gets called once per checked-out or updated file, passed a fsl_ckup_state instance with information a...
Definition checkout.h:1786
bool setMtime
If true, the checkout/update processes will calculate the (synthetic) mtime of each extracted file an...
Definition checkout.h:1831
bool dryRun
If true, the extraction process will "go through the motions" but will not write any files to disk.
Definition checkout.h:1849
fsl_id_t checkinRid
The version of the repostitory to check out or update.
Definition checkout.h:1779
fsl_confirmer confirmer
An optional "confirmer" for answering questions about file overwrites and deletions posed by the chec...
Definition checkout.h:1814
void * callbackState
State to be passed to this->callback via the fsl_ckup_state::callbackState member.
Definition checkout.h:1792
State to be passed to fsl_ckup_f() implementations via calls to fsl_repo_ckout() and fsl_ckout_update...
Definition checkout.h:1676
bool dryRun
True if the current checkout/update is running in dry-run mode, else false.
Definition checkout.h:1767
fsl_ckup_fchange_e fileChangeType
Vaguely describes the type of change the current call into the fsl_ckup_f() represents.
Definition checkout.h:1720
fsl_int_t size
The size of the extracted file, in bytes.
Definition checkout.h:1761
fsl_repo_extract_state const * extractState
The core SCM state for the just-extracted file.
Definition checkout.h:1695
void * callbackState
Optional client-dependent state for use in the fsl_ckup_f() callback.
Definition checkout.h:1701
fsl_time_t mtime
If fsl_repo_ckout()'s or fsl_ckout_update()'s options specified that the mtime should be set on each ...
Definition checkout.h:1754
fsl_ckup_rm_state_e fileRmInfo
Indicates whether the file was removed by the process:
Definition checkout.h:1735
A fsl_confirm_callback_f and its callback state, packaged into a neat little struct for easy copy/rep...
Definition util.h:6128
The main Fossil "context" type.
Definition internal.h:400
A container type for lists of db record IDs.
Definition util.h:5694
Generic list container type.
Definition util.h:156
UNDER CONSTRUCTION.
Definition checkout.h:2765
fsl_merge_type_e mergeType
Specifies the merge type to perform.
Definition checkout.h:2788
fsl_merge_f callback
Gets called once per merge-updated file, passed a fsl_ckup_state instance with information about the ...
Definition checkout.h:2807
bool scanForChanges
A hint to fsl_ckout_merge() about whether it needs to scan the checkout for changes.
Definition checkout.h:2820
void * callbackState
Client-defined state for use with this->callback.
Definition checkout.h:2811
bool dryRun
If true, the extraction process will "go through the motions" but will not write any files to disk.
Definition checkout.h:2830
unsigned short debug
This flag is not part of the public API and will be removed once the merge operation's development ha...
Definition checkout.h:2835
fsl_id_t baselineRid
The version of the most recent common ancestor.
Definition checkout.h:2782
fsl_id_t mergeRid
The version of the repostitory to merge into the current checkout.
Definition checkout.h:2770
UNDER CONSTRUCTION!
Definition checkout.h:2675
char const * priorName
If this->fileChangeType is FSL_MERGE_FCHANGE_RENAMED then this is the previous name of the file,...
Definition checkout.h:2697
char const * filename
The checkout-relative name of the file affected by the merge.
Definition checkout.h:2691
fsl_merge_opt const * opt
The options object which drives the current fsl_ckout_merge() run.
Definition checkout.h:2684
fsl_merge_fchange_e fileChangeType
Indicates the state of the file currently being merged.
Definition checkout.h:2705
fsl_ckup_rm_state_e fileRmInfo
Indicates whether the current file was removed.
Definition checkout.h:2713
fsl_cx * f
The fsl_cx object for which the current merge is running.
Definition checkout.h:2679
Callback state for use with fsl_repo_extract_f() implementations to stream a given version of a repos...
Definition repo.h:2509
Under construction.
Definition checkout.h:1472
char const * targetDir
Name of the target directory, which must already exist.
Definition checkout.h:1480
bool checkForOpenedCkout
If true, the checkout-open process will look for an opened checkout in the target directory and its p...
Definition checkout.h:1514
fsl_file_overwrite_policy_e fileOverwritePolicy
Policy for how to handle overwrites of files extracted from a newly-opened checkout.
Definition checkout.h:1499
char const * ckoutDbFile
The filename, with no directory components, of the desired checkout db name.
Definition checkout.h:1490
bool dbOverwritePolicy
fsl_repo_open_ckout() installs the fossil checkout schema.
Definition checkout.h:1507
char * fsl_uuid_str
fsl_uuid_str and fsl_uuid_cstr are "for documentation andreadability purposes" typedefs used to denot...
Definition util.h:72
char const * fsl_uuid_cstr
The const counterpart of fsl_uuid_str.
Definition util.h:80