libfossil
checkout.h File Reference

fossil-checkout.h declares APIs specifically dealing with checkout-side state, as opposed to purely repository-db-side state or non-content-related APIs. More...

#include "db.h"
#include "repo.h"
Include dependency graph for checkout.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  fsl_checkin_opt
 Parameters for fsl_checkin_commit(). More...
struct  fsl_checkin_queue_opt
 Options object type used by fsl_checkin_enqueue() and fsl_checkin_dequeue(). More...
struct  fsl_ckout_manage_opt
 Options for use with fsl_ckout_manage(). More...
struct  fsl_ckout_manage_state
 State passed to fsl_ckout_manage_f() callback. More...
struct  fsl_ckout_rename_opt
 Options object for use with fsl_ckout_rename(). More...
struct  fsl_ckout_revert_opt
 Options for passing to fsl_ckout_revert(). More...
struct  fsl_ckout_unmanage_opt
 Options for use with fsl_ckout_unmanage(). More...
struct  fsl_ckout_unmanage_state
 State passed to fsl_ckout_unmanage_f() callback. More...
struct  fsl_ckup_opt
 Options for use with fsl_repo_ckout() and fsl_ckout_update(). More...
struct  fsl_ckup_state
 State to be passed to fsl_ckup_f() implementations via calls to fsl_repo_ckout() and fsl_ckout_update(). More...
struct  fsl_merge_opt
 UNDER CONSTRUCTION. More...
struct  fsl_merge_state
 UNDER CONSTRUCTION! More...
struct  fsl_repo_open_ckout_opt
 Under construction. More...

Macros

#define fsl_checkin_opt_empty_m
 Empty-initialized fsl_checkin_opt instance, intended for use in const-copy constructing.
#define fsl_checkin_queue_opt_empty_m
 Initialized-with-defaults fsl_checkin_queue_opt structure, intended for const-copy initialization.
#define fsl_ckout_manage_opt_empty_m
 Initialized-with-defaults fsl_ckout_manage_opt instance, intended for use in const-copy initialization.
#define fsl_ckout_rename_opt_empty_m   {NULL,NULL,true,false,false,NULL,NULL}
 Initialized-with-defaults fsl_ckout_rename_opt structure, intended for const-copy initialization.
#define fsl_ckout_revert_opt_empty_m
 Initialized-with-defaults fsl_ckout_revert_opt instance, intended for use in const-copy initialization.
#define fsl_ckout_unmanage_opt_empty_m
 Initialized-with-defaults fsl_ckout_unmanage_opt instance, intended for use in const-copy initialization.
#define fsl_ckup_opt_m
 Empty-initialized fsl_ckup_opt const-copy constructor.
#define fsl_merge_opt_empty_m
 Initialized-with-defaults fsl_merge_opt structure, intended for const-copy initialization.
#define fsl_repo_open_ckout_opt_m
 Empty-initialized fsl_repo_open_ckout_opt const-copy constructer.

Typedefs

typedef 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 enqueued/dequeued via fsl_checkin_enqueue() and fsl_checkin_dequeue().
typedef struct fsl_checkin_queue_opt fsl_checkin_queue_opt
 Convenience typedef.
typedef enum fsl_ckout_change_e fsl_ckout_change_e
typedef 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().
typedef int(* fsl_ckout_manage_f) (fsl_ckout_manage_state const *mst, bool *include)
 Callback type for use with fsl_ckout_manage_opt().
typedef struct fsl_ckout_manage_opt fsl_ckout_manage_opt
 Convenience typedef and required forward decl.
typedef struct fsl_ckout_manage_state fsl_ckout_manage_state
 Convenience typedef.
typedef 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().
typedef struct fsl_ckout_rename_opt fsl_ckout_rename_opt
 Convenience typedef.
typedef enum fsl_ckout_revert_e fsl_ckout_revert_e
typedef int(* fsl_ckout_revert_f) (char const *zFilename, fsl_ckout_revert_e changeType, void *callbackState)
 Callback type for use with fsl_ckout_revert().
typedef struct fsl_ckout_revert_opt fsl_ckout_revert_opt
typedef int(* fsl_ckout_unmanage_f) (fsl_ckout_unmanage_state const *ums)
 Callback type for use with fsl_ckout_unmanage().
typedef struct fsl_ckout_unmanage_opt fsl_ckout_unmanage_opt
 Convenience typedef and required forward decl.
typedef struct fsl_ckout_unmanage_state fsl_ckout_unmanage_state
 Convenience typedef.
typedef int(* fsl_ckup_f) (fsl_ckup_state const *cState)
 A callback type for use with fsl_ckup_state.
typedef enum fsl_ckup_fchange_e fsl_ckup_fchange_e
typedef struct fsl_ckup_opt fsl_ckup_opt
typedef enum fsl_ckup_rm_state_e fsl_ckup_rm_state_e
typedef struct fsl_ckup_state fsl_ckup_state
typedef enum fsl_cx_manifest_mask_e fsl_cx_manifest_mask_e
typedef enum fsl_file_overwrite_policy_e fsl_file_overwrite_policy_e
typedef int(* fsl_merge_f) (fsl_merge_state const *const)
 Callback type for use with fsl_merge_opt and fsl_ckout_merge().
typedef enum fsl_merge_fchange_e fsl_merge_fchange_e
typedef struct fsl_merge_opt fsl_merge_opt
 Reqired forward decl.
typedef struct fsl_merge_state fsl_merge_state
typedef enum fsl_merge_type_e fsl_merge_type_e
typedef struct fsl_repo_open_ckout_opt fsl_repo_open_ckout_opt
typedef enum fsl_vfile_change_e fsl_vfile_change_e

Enumerations

enum  fsl_ckout_change_e {
  FSL_CKOUT_CHANGE_NONE = 0 ,
  FSL_CKOUT_CHANGE_MOD = FSL_VFILE_CHANGE_MOD ,
  FSL_CKOUT_CHANGE_MERGE_MOD = FSL_VFILE_CHANGE_MERGE_MOD ,
  FSL_CKOUT_CHANGE_MERGE_ADD = FSL_VFILE_CHANGE_MERGE_ADD ,
  FSL_CKOUT_CHANGE_INTEGRATE_MOD = FSL_VFILE_CHANGE_INTEGRATE_MOD ,
  FSL_CKOUT_CHANGE_INTEGRATE_ADD = FSL_VFILE_CHANGE_INTEGRATE_ADD ,
  FSL_CKOUT_CHANGE_IS_EXEC = FSL_VFILE_CHANGE_IS_EXEC ,
  FSL_CKOUT_CHANGE_BECAME_SYMLINK = FSL_VFILE_CHANGE_BECAME_SYMLINK ,
  FSL_CKOUT_CHANGE_NOT_EXEC = FSL_VFILE_CHANGE_NOT_EXEC ,
  FSL_CKOUT_CHANGE_NOT_SYMLINK = FSL_VFILE_CHANGE_NOT_SYMLINK ,
  FSL_CKOUT_CHANGE_ADDED = FSL_CKOUT_CHANGE_NOT_SYMLINK + 1000 ,
  FSL_CKOUT_CHANGE_REMOVED ,
  FSL_CKOUT_CHANGE_MISSING ,
  FSL_CKOUT_CHANGE_RENAMED
}
 Change-type flags for use with fsl_ckout_changes_visit() and friends. More...
enum  fsl_ckout_revert_e {
  FSL_REVERT_NONE = 0 ,
  FSL_REVERT_UNMANAGE ,
  FSL_REVERT_REMOVE ,
  FSL_REVERT_RENAME ,
  FSL_REVERT_PERMISSIONS ,
  FSL_REVERT_CONTENTS
}
 Change-type values for use with fsl_ckout_revert_f() callbacks. More...
enum  fsl_ckout_sig_e {
  FSL_VFILE_CKSIG_NONE = 0 ,
  FSL_VFILE_CKSIG_ENOTFILE = 0x001 ,
  FSL_VFILE_CKSIG_HASH = 0x002 ,
  FSL_VFILE_CKSIG_SETMTIME = 0x004 ,
  FSL_VFILE_CKSIG_KEEP_OTHERS = 0x008 ,
  FSL_VFILE_CKSIG_WRITE_CKOUT_VERSION = 0x010
}
 A bitmask of flags for fsl_vfile_changes_scan(). More...
enum  fsl_ckup_fchange_e {
  FSL_CKUP_FCHANGE_INVALID = -1 ,
  FSL_CKUP_FCHANGE_NONE = 0 ,
  FSL_CKUP_FCHANGE_ADDED ,
  FSL_CKUP_FCHANGE_ADD_PROPAGATED ,
  FSL_CKUP_FCHANGE_RM ,
  FSL_CKUP_FCHANGE_RM_PROPAGATED ,
  FSL_CKUP_FCHANGE_UPDATED ,
  FSL_CKUP_FCHANGE_UPDATED_BINARY ,
  FSL_CKUP_FCHANGE_MERGED ,
  FSL_CKUP_FCHANGE_CONFLICT_MERGED ,
  FSL_CKUP_FCHANGE_CONFLICT_ADDED ,
  FSL_CKUP_FCHANGE_CONFLICT_ADDED_UNMANAGED ,
  FSL_CKUP_FCHANGE_CONFLICT_RM ,
  FSL_CKUP_FCHANGE_CONFLICT_SYMLINK ,
  FSL_CKUP_FCHANGE_CONFLICT_BINARY ,
  FSL_CKUP_FCHANGE_RENAMED ,
  FSL_CKUP_FCHANGE_EDITED
}
 This enum lists the various types of individual file change states which can happen during a checkout, update, or merge. More...
enum  fsl_ckup_rm_state_e {
  FSL_CKUP_RM_NOT = 0 ,
  FSL_CKUP_RM_KEPT ,
  FSL_CKUP_RM
}
 State values for use with fsl_ckup_state::fileRmInfo. More...
enum  fsl_cx_manifest_mask_e {
  FSL_MANIFEST_MAIN = 0x001 ,
  FSL_MANIFEST_UUID = 0x010 ,
  FSL_MANIFEST_TAGS = 0x100
}
 Bitmask used by fsl_ckout_manifest_setting() and fsl_ckout_manifest_write(). More...
enum  fsl_file_overwrite_policy_e {
  FSL_OVERWRITE_ERROR = 0 ,
  FSL_OVERWRITE_ALWAYS ,
  FSL_OVERWRITE_NEVER
}
 File-overwrite policy values for use with fsl_ckup_opt and friends. More...
enum  fsl_merge_fchange_e {
  FSL_MERGE_FCHANGE_NONE = 0 ,
  FSL_MERGE_FCHANGE_ADDED ,
  FSL_MERGE_FCHANGE_COPIED ,
  FSL_MERGE_FCHANGE_RM ,
  FSL_MERGE_FCHANGE_MERGED ,
  FSL_MERGE_FCHANGE_CONFLICT_MERGED ,
  FSL_MERGE_FCHANGE_CONFLICT_ADDED_UNMANAGED ,
  FSL_MERGE_FCHANGE_CONFLICT_SYMLINK ,
  FSL_MERGE_FCHANGE_CONFLICT_BINARY ,
  FSL_MERGE_FCHANGE_RENAMED ,
  FSL_MERGE_FCHANGE_count
}
 File change types for use with fsl_merge_state::fileChangeType. More...
enum  fsl_merge_type_e {
  FSL_MERGE_TYPE_NORMAL = 0 ,
  FSL_MERGE_TYPE_INTEGRATE = -4 ,
  FSL_MERGE_TYPE_CHERRYPICK = -1 ,
  FSL_MERGE_TYPE_BACKOUT = -2
}
 Merge type enum for use with fsl_merge_opt::mergeType. More...
enum  fsl_vfile_change_e {
  FSL_VFILE_CHANGE_NONE = 0 ,
  FSL_VFILE_CHANGE_MOD = 1 ,
  FSL_VFILE_CHANGE_MERGE_MOD = 2 ,
  FSL_VFILE_CHANGE_MERGE_ADD = 3 ,
  FSL_VFILE_CHANGE_INTEGRATE_MOD = 4 ,
  FSL_VFILE_CHANGE_INTEGRATE_ADD = 5 ,
  FSL_VFILE_CHANGE_IS_EXEC = 6 ,
  FSL_VFILE_CHANGE_BECAME_SYMLINK = 7 ,
  FSL_VFILE_CHANGE_NOT_EXEC = 8 ,
  FSL_VFILE_CHANGE_NOT_SYMLINK = 9
}
 Hard-coded range of values of the vfile.chnged db field. More...

Functions

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 checkin in which it was modified (as reported by fsl_mtime_of_manifest()).
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_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 directory, from the checkin queue.
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_enqueue() and tags added via fsl_checkin_T_add().
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 commit (see fsl_checkin_commit()).
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_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_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 object.
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 current checkout's branch.
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_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 negative).
FSL_EXPORT int fsl_ckout_clear_db (fsl_cx *f)
 Clears all contents from f's checkout database, including the vfile table, vmerge table, and some of the vvar table.
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 database file named one of (FOSSIL, .fslckout).
FSL_EXPORT char const ** fsl_ckout_dbnames (void)
 Returns an array of strings with the base names of valid fossil checkout databases.
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 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 zOrigName to a form suitable for use as an in-repo filename, appending the results to pOut.
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 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), returns true, else returns false.
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 to-be-added file, or updates an existing record if one exists.
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 a checkout directory, as specified by the repository's 'manifest' configuration setting, and sets *m to a bitmask indicating which of those are enabled.
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 the the checkout's root directory.
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_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_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 within the current checkout.
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 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 version.
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_update (fsl_cx *f, fsl_ckup_opt const *opt)
 UNDER CONSTRUCTION.
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_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 that routine.
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 vfile.vid == vid.
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 found under a subdirectory named zName (with no trailing slash).
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, else false.
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 a description of the problem and returns non-0: FSL_RC_RANGE or (if updating the error state fails) FSL_RC_OOM.
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 that only a cursory check is done - the db is not opened and validated), the name of that database file (minus the directory part) is returned, else NULL is returned.
FSL_EXPORT char const * fsl_preferred_ckout_db_name (void)
 Returns the base name of the current platform's checkout database file.
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->checkinRid to the root directory of f's currently-opened checkout.
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.
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 ID then compares files listed in it against files in the checkout directory, updating vfile's status for the current checkout version id as its goes.
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 checkin manifest.
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_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.vid value.
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 vid.

Variables

FSL_EXPORT const fsl_checkin_opt fsl_checkin_opt_empty
 Empty-initialized fsl_checkin_opt instance, intended for use in copy-constructing.
const fsl_checkin_queue_opt fsl_checkin_queue_opt_empty
 Initialized-with-defaults fsl_checkin_queue_opt structure, intended for non-const copy initialization.
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 initialization.
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_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 initialization.
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 initialization.
FSL_EXPORT const fsl_ckup_opt fsl_ckup_opt_empty
 Empty-initialised fsl_ckup_opt instance.
const fsl_merge_opt fsl_merge_opt_empty
 Initialized-with-defaults fsl_merge_opt structure, intended for non-const copy initialization.
FSL_EXPORT const fsl_repo_open_ckout_opt fsl_repo_open_ckout_opt_empty
 Empty-initialised fsl_repo_open_ckout_opt instance.

Detailed Description

fossil-checkout.h declares APIs specifically dealing with checkout-side state, as opposed to purely repository-db-side state or non-content-related APIs.

Definition in file checkout.h.

Macro Definition Documentation

◆ fsl_checkin_opt_empty_m

#define fsl_checkin_opt_empty_m
Value:
{ \
.message = NULL, \
.messageMimeType = NULL, \
.user = NULL, \
.branch = NULL, \
.bgColor = NULL, \
.isPrivate = false, \
.calcRCard = true, \
.integrate = false, \
.allowMergeConflict = false,\
.scanForChanges = true,\
.rmRemovedFiles = false,\
.dryRun = false, \
.deltaPolicy = 0, \
.julianTime = 0.0, \
.closeBranch = NULL, \
.dumpManifestFile = NULL \
}

Empty-initialized fsl_checkin_opt instance, intended for use in const-copy constructing.

Definition at line 1257 of file checkout.h.

◆ fsl_checkin_queue_opt_empty_m

#define fsl_checkin_queue_opt_empty_m
Value:
{ \
NULL/*filename*/,true/*relativeToCwd*/, \
NULL/*vfileIds*/, \
true/*scanForChanges*/,true/*onlyModifiedFiles*/, \
NULL/*callback*/,NULL/*callbackState*/ \
}

Initialized-with-defaults fsl_checkin_queue_opt structure, intended for const-copy initialization.

Definition at line 895 of file checkout.h.

◆ fsl_ckout_manage_opt_empty_m

#define fsl_ckout_manage_opt_empty_m
Value:
{\
NULL/*filename*/, true/*relativeToCwd*/, true/*checkIgnoreGlobs*/, \
NULL/*callback*/, NULL/*callbackState*/, \
{/*counts*/ 0/*added*/, 0/*updated*/, 0/*skipped*/} \
}

Initialized-with-defaults fsl_ckout_manage_opt instance, intended for use in const-copy initialization.

Definition at line 345 of file checkout.h.

◆ fsl_ckout_rename_opt_empty_m

#define fsl_ckout_rename_opt_empty_m   {NULL,NULL,true,false,false,NULL,NULL}

Initialized-with-defaults fsl_ckout_rename_opt structure, intended for const-copy initialization.

Definition at line 3004 of file checkout.h.

◆ fsl_ckout_revert_opt_empty_m

#define fsl_ckout_revert_opt_empty_m
Value:
{ \
NULL/*filename*/,NULL/*vfileIds*/,true/*relativeToCwd*/,true/*scanForChanges*/, \
NULL/*callback*/,NULL/*callbackState*/ \
}

Initialized-with-defaults fsl_ckout_revert_opt instance, intended for use in const-copy initialization.

Definition at line 2214 of file checkout.h.

◆ fsl_ckout_unmanage_opt_empty_m

#define fsl_ckout_unmanage_opt_empty_m
Value:
{\
NULL/*filename*/, NULL/*vfileIds*/,\
true/*relativeToCwd*/,true/*scanForChanges*/, \
NULL/*callback*/, NULL/*callbackState*/ \
}

Initialized-with-defaults fsl_ckout_unmanage_opt instance, intended for use in const-copy initialization.

Definition at line 516 of file checkout.h.

◆ fsl_ckup_opt_m

#define fsl_ckup_opt_m
Value:
{\
-1/*checkinRid*/, NULL/*callback*/, NULL/*callbackState*/, \
fsl_confirmer_empty_m/*confirmer*/,\
false/*setMtime*/, true/*scanForChanges*/,false/*dryRun*/ \
}
#define fsl_confirmer_empty_m
Empty-initialized fsl_confirmer instance for const-copy initialization.
Definition util.h:6145

Empty-initialized fsl_ckup_opt const-copy constructor.

Definition at line 1856 of file checkout.h.

◆ fsl_merge_opt_empty_m

#define fsl_merge_opt_empty_m
Value:
{-1/*mergeRid*/,0/*baselineRid*/, \
FSL_MERGE_TYPE_NORMAL/*mergeType*/, \
NULL/*callback*/, NULL/*callbackState*/, \
true/*scanForChanges*/, \
false/*dryRun*/,0/*debug*/}
@ FSL_MERGE_TYPE_NORMAL
Indicates a normal merge.
Definition checkout.h:2733

Initialized-with-defaults fsl_merge_opt structure, intended for const-copy initialization.

Definition at line 2847 of file checkout.h.

◆ fsl_repo_open_ckout_opt_m

#define fsl_repo_open_ckout_opt_m
Value:
{ \
NULL/*targetDir*/, NULL/*ckoutDbFile*/, \
FSL_OVERWRITE_ERROR/*fileOverwritePolicy*/, \
false/*dbOverwritePolicy*/, \
-1/*checkForOpenedCkout*/ \
}
@ FSL_OVERWRITE_ERROR
Indicates that an error should be triggered if a file would be overwritten.
Definition checkout.h:1425

Empty-initialized fsl_repo_open_ckout_opt const-copy constructer.

Definition at line 1521 of file checkout.h.

Typedef Documentation

◆ fsl_checkin_queue_f

typedef 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 enqueued/dequeued via fsl_checkin_enqueue() and fsl_checkin_dequeue().

This function gets passed the checkout-relative name of the file being enqueued/dequeued and the client-provided state pointer which was passed to the relevant API. It must return 0 on success. If it returns non-0, the API on whose behalf this callback is invoked will propagate that error code back to the caller.

The intent of this callback is simply to report changes to the client, not to perform validation. Thus such callbacks "really should not fail" unless, e.g., they encounter an OOM condition or some such. Any validation required by the client should be performed before calling fsl_checkin_enqueue() resp. fsl_checkin_dequeue().

Definition at line 816 of file checkout.h.

◆ fsl_checkin_queue_opt

typedef struct fsl_checkin_queue_opt fsl_checkin_queue_opt

Convenience typedef.

Definition at line 891 of file checkout.h.

◆ fsl_ckout_change_e

Definition at line 664 of file checkout.h.

◆ fsl_ckout_changes_f

typedef 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().

Implementions will receive the last argument passed to fsl_ckout_changes_visit() as their first argument. The second argument indicates the type of change and the third holds the repository-relative name of the file.

If changes is FSL_CKOUT_CHANGE_RENAMED then origName will hold the original name, else it will be NULL.

Implementations must return 0 on success, non-zero on error. On error any looping performed by fsl_ckout_changes_visit() will stop and this function's result code will be returned.

See also
fsl_ckout_changes_visit()

Definition at line 691 of file checkout.h.

◆ fsl_ckout_manage_f

typedef int(* fsl_ckout_manage_f) (fsl_ckout_manage_state const *mst, bool *include)

Callback type for use with fsl_ckout_manage_opt().

It should inspect the given (mst->filename) using whatever criteria it likes, set include to true or false to indicate whether the filename is okay to include the current add-file-to-repo operation, and return 0.

If it returns non-0 the add-file-to-repo process will end and that error code will be reported to its caller. Such result codes must come from the FSL_RC_xxx family. They may report details of the error via fsl_cx_err_set() with the mst->f object.

It will be passed a name which is relative to the top-most checkout directory.

The final argument is not used by the library, but is passed on as-is from the fsl_ckout_manage_opt::callbackState pointer which is passed to fsl_ckout_manage().

Definition at line 246 of file checkout.h.

◆ fsl_ckout_manage_opt

typedef struct fsl_ckout_manage_opt fsl_ckout_manage_opt

Convenience typedef and required forward decl.

Definition at line 185 of file checkout.h.

◆ fsl_ckout_manage_state

typedef struct fsl_ckout_manage_state fsl_ckout_manage_state

Convenience typedef.

Definition at line 226 of file checkout.h.

◆ fsl_ckout_rename_f

typedef 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().

It gets called once per iteration of a rename operation, along with the original options object for the rename and:

  • zSrcName is the checkout-relative original name of the file.
  • zDestname is the checkout-relative new name of the file.

Both strings are owned by the calling operation and will be freed soon after this call returns. If the client needs them, they must make copies.

It must returns 0 on success. If it returns non-0 then the current renaming op is cancelled (rolled back) and the result code is propagated back to the caller of fsl_ckout_rename().

This gets called immediately after the associated db record is modified and before the filesystem move (if any) is performed.

Design note: ideally the callback would be called after the filesystem move, but the way the moves are currently processed (as a batch after the db updates, noting that those updates may trigger variou error conditions) precludes that. Alternately, we could delay the callback until the file-move phase (noting that the file-move step is optional), and that might be a sensible change to make.

Definition at line 2955 of file checkout.h.

◆ fsl_ckout_rename_opt

typedef struct fsl_ckout_rename_opt fsl_ckout_rename_opt

Convenience typedef.

Definition at line 2927 of file checkout.h.

◆ fsl_ckout_revert_e

Definition at line 2152 of file checkout.h.

◆ fsl_ckout_revert_f

typedef int(* fsl_ckout_revert_f) (char const *zFilename, fsl_ckout_revert_e changeType, void *callbackState)

Callback type for use with fsl_ckout_revert().

For each reverted file it gets passed the checkout-relative filename, type of change, and the callback state pointer which was passed to fsl_ckout_revert(). If it returns non-0, the revert process will end in an error and that code will be propagated back to the caller. In such cases, any files reverted up until that point will still be reverted on disk but the reversion in the database will be rolled back. A change scan (e.g. fsl_ckout_changes_scan()) will restore balance to that equation, but these callbacks should only return non-0 in for catastrophic failure.

Definition at line 2165 of file checkout.h.

◆ fsl_ckout_revert_opt

typedef struct fsl_ckout_revert_opt fsl_ckout_revert_opt

Definition at line 2209 of file checkout.h.

◆ fsl_ckout_unmanage_f

typedef int(* fsl_ckout_unmanage_f) (fsl_ckout_unmanage_state const *ums)

Callback type for use with fsl_ckout_unmanage().

It is called by the removal process, immediately after a file is "removed" from SCM management (a.k.a. when the file becomes "unmanaged").

If it returns non-0 the unmanage process will end and that error code will be reported to its caller. Such result codes must come from the FSL_RC_xxx family. They may report details of the error via fsl_cx_err_set() with the ums->f object.

The object passed to it will hold the name of the file being unmanaged, relative to the top-most checkout directory. The client is free to unlink the file from the filesystem if they like - the library does not do so automatically

Definition at line 460 of file checkout.h.

◆ fsl_ckout_unmanage_opt

typedef struct fsl_ckout_unmanage_opt fsl_ckout_unmanage_opt

Convenience typedef and required forward decl.

Definition at line 403 of file checkout.h.

◆ fsl_ckout_unmanage_state

typedef struct fsl_ckout_unmanage_state fsl_ckout_unmanage_state

Convenience typedef.

Definition at line 442 of file checkout.h.

◆ fsl_ckup_f

typedef int(* fsl_ckup_f) (fsl_ckup_state const *cState)

A callback type for use with fsl_ckup_state.

It gets called via fsl_repo_ckout() and fsl_ckout_update() to report progress of the extraction process. It gets called after one of those functions has successfully extracted a file or skipped over it because the file existed and the checkout options specified to leave existing files in place. It must return 0 on success, and non-0 will end the extraction process, propagating that result code back to the caller. If this callback fails, the checkout's contents may be left in an undefined state, with some files updated and others not. All database-side data will be consistent (the transaction is rolled back) but filesystem-side changes may not be.

Definition at line 1578 of file checkout.h.

◆ fsl_ckup_fchange_e

Definition at line 1670 of file checkout.h.

◆ fsl_ckup_opt

typedef struct fsl_ckup_opt fsl_ckup_opt

Definition at line 1851 of file checkout.h.

◆ fsl_ckup_rm_state_e

Definition at line 1461 of file checkout.h.

◆ fsl_ckup_state

typedef struct fsl_ckup_state fsl_ckup_state

Definition at line 1564 of file checkout.h.

◆ fsl_cx_manifest_mask_e

Definition at line 2003 of file checkout.h.

◆ fsl_file_overwrite_policy_e

Definition at line 1436 of file checkout.h.

◆ fsl_merge_f

typedef int(* fsl_merge_f) (fsl_merge_state const *const)

Callback type for use with fsl_merge_opt and fsl_ckout_merge().

Definition at line 2720 of file checkout.h.

◆ fsl_merge_fchange_e

Definition at line 2644 of file checkout.h.

◆ fsl_merge_opt

typedef struct fsl_merge_opt fsl_merge_opt

Reqired forward decl.

Definition at line 2647 of file checkout.h.

◆ fsl_merge_state

typedef struct fsl_merge_state fsl_merge_state

Definition at line 2715 of file checkout.h.

◆ fsl_merge_type_e

Definition at line 2758 of file checkout.h.

◆ fsl_repo_open_ckout_opt

typedef struct fsl_repo_open_ckout_opt fsl_repo_open_ckout_opt

Definition at line 1516 of file checkout.h.

◆ fsl_vfile_change_e

Definition at line 590 of file checkout.h.

Enumeration Type Documentation

◆ fsl_ckout_change_e

Change-type flags for use with fsl_ckout_changes_visit() and friends.

TODO: consolidate this with fsl_vfile_change_e insofar as possible. There are a few checkout change statuses not reflected in fsl_vfile_change_e.

Enumerator
FSL_CKOUT_CHANGE_NONE 

Sentinel placeholder value.

FSL_CKOUT_CHANGE_MOD 

Indicates that a file was modified in some unspecified way.

FSL_CKOUT_CHANGE_MERGE_MOD 

Indicates that a file was modified as the result of a merge.

FSL_CKOUT_CHANGE_MERGE_ADD 

Indicates that a file was added as the result of a merge.

FSL_CKOUT_CHANGE_INTEGRATE_MOD 

Indicates that a file was modified as the result of an integrate-merge.

FSL_CKOUT_CHANGE_INTEGRATE_ADD 

Indicates that a file was added as the result of an integrate-merge.

FSL_CKOUT_CHANGE_IS_EXEC 

Indicates that the file gained the is-executable trait but is otherwise unmodified.

FSL_CKOUT_CHANGE_BECAME_SYMLINK 

Indicates that the file has changed to a symlink.

FSL_CKOUT_CHANGE_NOT_EXEC 

Indicates that the file lost the is-executable trait but is otherwise unmodified.

FSL_CKOUT_CHANGE_NOT_SYMLINK 

Indicates that the file was previously a symlink but is now a plain file.

FSL_CKOUT_CHANGE_ADDED 

Indicates that a file was added.

FSL_CKOUT_CHANGE_REMOVED 

Indicates that a file was removed from SCM management.

FSL_CKOUT_CHANGE_MISSING 

Indicates that a file is missing from the local checkout.

FSL_CKOUT_CHANGE_RENAMED 

Indicates that a file was renamed.

Definition at line 600 of file checkout.h.

◆ fsl_ckout_revert_e

Change-type values for use with fsl_ckout_revert_f() callbacks.

Enumerator
FSL_REVERT_NONE 

Sentinel value.

FSL_REVERT_UNMANAGE 

File was previously queued for addition but unqueued by the revert process.

FSL_REVERT_REMOVE 

File was previously queued for removal but unqueued by the revert process.

If the file's contents or permissions were also reverted then the file is reported as FSL_REVERT_PERMISSIONS or FSL_REVERT_CONTENTS instead.

FSL_REVERT_RENAME 

File was previously scheduled to be renamed, but the rename was reverted.

The name reported to the callback is the original one. If a file was both modified and renamed, it will be flagged as renamed instead of modified, for consistency with the usage of fsl_ckup_fchange_e's FSL_CKUP_FCHANGE_RENAMED.

FIXME: this does not mean that the file on disk was actually renamed (if needed). That is TODO, pending addition of code to perform renames.

FSL_REVERT_PERMISSIONS 

File's permissions (only) were reverted.

FSL_REVERT_CONTENTS 

File's contents reverted.

This value trumps any others in this enum. Thus if a file's permissions and contents were reverted, or it was un-renamed and its contents reverted, it will be reported using this enum entry.

Definition at line 2115 of file checkout.h.

◆ fsl_ckout_sig_e

A bitmask of flags for fsl_vfile_changes_scan().

Enumerator
FSL_VFILE_CKSIG_NONE 

The empty flags set.

FSL_VFILE_CKSIG_ENOTFILE 

Non-file/non-link FS objects trigger an error.

FSL_VFILE_CKSIG_HASH 

Verify file content using hashing, regardless of whether or not file timestamps differ.

FSL_VFILE_CKSIG_SETMTIME 

For unchanged or changed-by-merge files, set the mtime to last check-out time, as determined by fsl_mtime_of_manifest_file().

FSL_VFILE_CKSIG_KEEP_OTHERS 

Indicates that when populating the vfile table, it should be not be cleared of entries for other checkins.

Normally we want to clear all versions except for the one we're working with, but at least a couple of use cases call for having multiple versions in vfile at once. Many algorithms generally assume only a single checkin's worth of state is in vfile and can get confused if that is not the case.

FSL_VFILE_CKSIG_WRITE_CKOUT_VERSION 

If set and fsl_vfile_changes_scan() is passed a version other than the pre-call checkout version, it will, when finished, write the given version in the "checkout" setting of the ckout.vvar table, effectively switching the checkout to that version.

It does not do this by default because it is sometimes necessary to have two versions in the vfile table at once and the operation doing so needs to control which version number is the current checkout.

Definition at line 720 of file checkout.h.

◆ fsl_ckup_fchange_e

This enum lists the various types of individual file change states which can happen during a checkout, update, or merge.

Enumerator
FSL_CKUP_FCHANGE_INVALID 

Sentinel value.

FSL_CKUP_FCHANGE_NONE 

Was unchanged between the previous and updated-to version, so no change was made to the on-disk file.

This is the only entry in the enum which is guaranteed to have a specific value: 0, so that it can be used as a boolean false.

FSL_CKUP_FCHANGE_ADDED 

Added to SCM in the updated-to version.

FSL_CKUP_FCHANGE_ADD_PROPAGATED 

Added to SCM in the current checkout version and carried over into the updated-to version.

FSL_CKUP_FCHANGE_RM 

Removed from SCM in the updated-to to version OR in the checked-out version but not yet committed.

a.k.a. it became "unmanaged."

Do we need to differentiate between those cases?

FSL_CKUP_FCHANGE_RM_PROPAGATED 

Removed from the checked-out version but not yet commited, so was carried over to the updated-to version.

FSL_CKUP_FCHANGE_UPDATED 

Updated or replaced without a merge by the checkout/update process.

FSL_CKUP_FCHANGE_UPDATED_BINARY 

Merge was not performed because at least one of the inputs appears to be binary.

The updated-to version overwrites the previous version in this case.

FSL_CKUP_FCHANGE_MERGED 

Updated with a merge by the update process.

FSL_CKUP_FCHANGE_CONFLICT_MERGED 

Special case of FSL_CKUP_FCHANGE_MERGED.

Merge was performed and conflicts were detected. The newly-updated file will contain conflict markers.

See also
fsl_buffer_contains_merge_marker()
FSL_CKUP_FCHANGE_CONFLICT_ADDED 

Added in the current checkout but also contained in the updated-to version.

The local copy takes precedence.

FSL_CKUP_FCHANGE_CONFLICT_ADDED_UNMANAGED 

Added by the updated-to version but a local unmanaged copy exists.

The local copy is overwritten, per historical fossil(1) convention (noting that fossil has undo support to allow one to avoid loss of such a file's contents).

TODO: use confirmer here to ask user whether to overwrite.

FSL_CKUP_FCHANGE_CONFLICT_RM 

Edited locally but removed from updated-to version.

Local edits will be left in the checkout tree.

FSL_CKUP_FCHANGE_CONFLICT_SYMLINK 

Cannot merge if one or both of the update/updating verions of a file is a symlink.

The updated-to version overwrites the previous version in this case.

We probably need a better name for this.

FSL_CKUP_FCHANGE_CONFLICT_BINARY 

Indicates that a merge of binary content was requested.

TODO: figure out why UPDATE uses the target version, instead of triggering an error here, and why MERGE does not do the same. fossil(1) simply skips over, with a warning, binaries during a merge.

FSL_CKUP_FCHANGE_RENAMED 

File was renamed in the updated-to version.

If a file is both modified and renamed, it is flagged as renamed instead of modified.

FSL_CKUP_FCHANGE_EDITED 

Locally modified.

This state appears only when "updating" a checkout to the same version.

Definition at line 1584 of file checkout.h.

◆ fsl_ckup_rm_state_e

State values for use with fsl_ckup_state::fileRmInfo.

Enumerator
FSL_CKUP_RM_NOT 

Indicates that the file was not removed in a given checkout.

Guaranteed to have the value 0 so that it is treated as boolean false. No other entries in this enum have well-defined values.

FSL_CKUP_RM_KEPT 

Indicates that a file was removed from a checkout but kept in the filesystem because it was locally modified.

FSL_CKUP_RM 

Indicates that a file was removed from a checkout and the filesystem, with the caveat that failed attempts to remove from the filesystem are ignored for Reasons but will be reported as if the unlink worked.

Definition at line 1441 of file checkout.h.

◆ fsl_cx_manifest_mask_e

Bitmask used by fsl_ckout_manifest_setting() and fsl_ckout_manifest_write().

Enumerator
FSL_MANIFEST_MAIN 

Coresponds to the file "manifest".

FSL_MANIFEST_UUID 

Coresponds to the file "manifest.uuid".

FSL_MANIFEST_TAGS 

Coresponds to the file "manifest.tags".

Definition at line 1995 of file checkout.h.

◆ fsl_file_overwrite_policy_e

File-overwrite policy values for use with fsl_ckup_opt and friends.

Enumerator
FSL_OVERWRITE_ERROR 

Indicates that an error should be triggered if a file would be overwritten.

FSL_OVERWRITE_ALWAYS 

Indicates that files should always be overwritten.

FSL_OVERWRITE_NEVER 

Indicates that files should never be overwritten, and silently skipped over.

This is almost never what one wants to do.

Definition at line 1422 of file checkout.h.

◆ fsl_merge_fchange_e

File change types for use with fsl_merge_state::fileChangeType.

Terminology used in some of the descriptions:

  • (P) is the "pivot" - the common ancestor for the merge.
  • (M) is the version being merged in to...
  • (V) is current checkout version into which (M) is being merged.

Maintenance reminder: this enum's values must start at 0 and increment sequentially, and FSL_MERGE_FCHANGE_count must be the final entry. This is to enable the creation of arrays, e.g. for keeping track (client-side) of how many times a given change type has been seen during a given merge run.

Enumerator
FSL_MERGE_FCHANGE_NONE 

Not currently used.

Merge does not (and cannot without some surgery) report state of files unaffected by a merge. This entry exists for the case that that changes. This is the only entry in the enum which is guaranteed to have a specific value: 0, so that it can be used as a boolean false.

FSL_MERGE_FCHANGE_ADDED 

File was added to (V) from (M).

FSL_MERGE_FCHANGE_COPIED 

File content was copied as-is from (M) to (V).

FSL_MERGE_FCHANGE_RM 

File was removed from (V) via (M).

a.k.a. it became "unmanaged."

FSL_MERGE_FCHANGE_MERGED 

Content from (M) was merged into (V).

FSL_MERGE_FCHANGE_CONFLICT_MERGED 

Special case of FSL_MERGE_FCHANGE_MERGED.

Merge was performed from (M) to (V) and conflicts were detected. The newly-updated file will contain conflict markers.

See also
fsl_buffer_contains_merge_marker()
FSL_MERGE_FCHANGE_CONFLICT_ADDED_UNMANAGED 

Added to (V) by (M) but a local unmanaged copy exists.

The local copy is overwritten, per historical fossil(1) convention (noting that fossil has undo support to allow one to avoid loss of such a file's contents).

FSL_MERGE_FCHANGE_CONFLICT_SYMLINK 

Cannot merge if one or both of the update/updating versions of a file is a symlink.

This case needs re-thinking. fossil(1) simply skips such merges with a warning but no error. This library has no warning mechanism other than to pass this code on to the fsl_merge_f() callback, so that's what we do.

For UPDATE ops, the updated-to version overwrites the previous version in this case. Why merge doesn't do that isn't clear, but it's probably because we can have any number of merge parents and choosing which one to use in the merge/replace case would be impossible.

FSL_MERGE_FCHANGE_CONFLICT_BINARY 

Indicates that a merge of binary content was requested.

We cannot merge binaries, so this indicates that the file in question was skipped over for merge purposes.

fossil(1) simply skips over, with a warning, binaries during a merge, so we do the same (for lack of a better option).

FSL_MERGE_FCHANGE_RENAMED 

File was renamed in the updated-to version.

If a file is both modified and renamed, it will be reported twice: once for each type of change. The new name is reported via fsl_merge_state::filename and the previous name via fsl_merge_state::priorName.

FSL_MERGE_FCHANGE_count 

This is the number of entries in this enum, for purposes of creating, e.g.

arrays of counters. This entry is never reported via a fsl_merge_state::fileChangeType.

Definition at line 2549 of file checkout.h.

◆ fsl_merge_type_e

Merge type enum for use with fsl_merge_opt::mergeType.

The values of these entries are fossil-magic values for the vmerge.id db field and must stay in sync with fossil's definition.

Enumerator
FSL_MERGE_TYPE_NORMAL 

Indicates a normal merge.

FSL_MERGE_TYPE_INTEGRATE 

Indicates an "integrate" merge, which tells the next checkin operation to apply a "closed" tag to the checkin from which this merge is performed (effectively closing its branch).

Certain merge-time state will force this merge type to silently behave like FSL_MERGE_TYPE_NORMAL:

  • If the being-merged-in content is marked as private.
  • If the being-merged-in content is not a leaf.
FSL_MERGE_TYPE_CHERRYPICK 

Indicates a cherrypick merge, pulling in only the changes made to a specific checkin without otherwise inheriting its lineage.

FSL_MERGE_TYPE_BACKOUT 

Indicates a backout merge, a reverse cherrypick, backing out any changes which were added by the corresponding fsl_merge_opt::mergeRid.

Definition at line 2729 of file checkout.h.

◆ fsl_vfile_change_e

Hard-coded range of values of the vfile.chnged db field.

These values are part of the fossil schema and must not be modified.

Enumerator
FSL_VFILE_CHANGE_NONE 

File is unchanged.

FSL_VFILE_CHANGE_MOD 

File edit.

FSL_VFILE_CHANGE_MERGE_MOD 

File changed due to a merge.

FSL_VFILE_CHANGE_MERGE_ADD 

File added by a merge.

FSL_VFILE_CHANGE_INTEGRATE_MOD 

File changed due to an integrate merge.

FSL_VFILE_CHANGE_INTEGRATE_ADD 

File added by an integrate merge.

FSL_VFILE_CHANGE_IS_EXEC 

File became executable but has unmodified contents.

FSL_VFILE_CHANGE_BECAME_SYMLINK 

File became a symlink whose target equals its old contents.

FSL_VFILE_CHANGE_NOT_EXEC 

File lost executable status but has unmodified contents.

FSL_VFILE_CHANGE_NOT_SYMLINK 

File lost symlink status and has contents equal to its old target.

Definition at line 568 of file checkout.h.

Function Documentation

◆ fsl_card_F_ckout_mtime()

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 checkin in which it was modified (as reported by fsl_mtime_of_manifest()).

vid is the checkin version to look at. If it's <=0, the current checkout will be used.

On success, returns 0 and:

  • If repoMtime is not NULL then (*repoMtime) is assigned to the result of fsl_mtime_of_manifest_file() for the given file.
  • If localMtime is not NULL then (*localMtime) is assigned to the checkout-local timestamp of the file.

Returns non-0 on error. Some of the potential results include:

  • FSL_RC_NOT_A_CKOUT.
  • FSL_RC_NOT_FOUND if the filename cannot be resolved in the requested version or cannot be stat()'d. This can happen if, e.g. fc's file has been renamed, but not yet checked in, in the current checkout. A potential TODO is to check for a (vfile.origname=fc->name) record and use vfile.pathname for the stat() call.
  • FSL_RC_OOM.

References FSL_EXPORT.

◆ fsl_checkin_commit()

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.

Its primary inputs is a list of files to commit. This list is provided by the client by calling fsl_checkin_enqueue() one or more times. If no files are explicitely selected (enqueued) then it calculates which local files have changed vs the current checkout and selects all of those.

Non-file inputs are provided via the opt parameter.

On success, it returns 0 and...

  • If newRid is not NULL, it is assigned the new checkin's RID value.
  • If newUuid is not NULL, it is assigned the new checkin's UUID value. Ownership of the bytes is passed to the caller, who must eventually pass them to fsl_free() to free them.

Note that the new RID and UUID can also be fetched afterwards by calling fsl_ckout_version_info().

On error non-0 is returned and f's error state may (depending on the nature of the problem) contain details about the problem. Note, however, that any error codes returned here may have arrived from several layers down in the internals, and may not have a single specific interpretation here. When possible/practical, f's error state gets updated with a human-readable description of the problem.

opt->dryRun: does not work properly, at least partially due to stale internal caches.

ACHTUNG: all pending checkin state is cleared by this function unless it fails basic argument validation. This means any queued files or tags need to be re-applied if the client wants to try again. That is somewhat of a bummer, but this behaviour is the only way we can ensure that then the pending checkin state does not get garbled on a second use. When in doubt about the state, the client should call fsl_checkin_discard() to clear it before try to re-commit. (Potential TODO: add a success/fail state flag to the checkin state and only clean up on success? OTOH, since something in the state likely caused the problem, we might not want to do that.)

Some of the more notable, potentially not obvious, error conditions:

  • Trying to commit against a closed leaf: FSL_RC_ACCESS. Doing so is not permitted by fossil(1), so we disallow it here.
  • An empty/NULL user name or commit message, or no files were selected which actually changed: FSL_RC_MISSING_INFO. In these cases f's error state describes the problem.
  • Some resource is not found (e.g. an expected RID/UUID could not be resolved): FSL_RC_NOT_FOUND. This would generally indicate some sort of data consistency problem. i.e. it's quite possibly very bad if this is returned.
  • If the checkin would result in no file-level changes vis-a-vis the current checkout, FSL_RC_NOOP is returned.

BUGS:

  • It cannot currently properly distinguish a "no-op" commit, one in which no files were modified or only their permissions were modifed.

TODO:

  • Honor the opt->dryRun flag. Getting this working has proven tricky because of stale cache issues.
See also
fsl_checkin_enqueue()
fsl_checkin_dequeue()
fsl_checkin_discard()
fsl_checkin_T_add()

References FSL_EXPORT.

◆ fsl_checkin_dequeue()

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 directory, from the checkin queue.

Returns 0 on succes. This function does no validation on whether a given file(s) actually exist(s), it simply asks the internals to clean up matching strings from the checkout's vfile table. Specifically, it does not return an error if this operation finds no entries to dequeue.

If opt->filename is empty or NULL then ALL files are unqueued from the pending checkin.

If opt->relativeToCwd is true (non-0) then opt->filename is resolved based on the current directory, otherwise it is resolved based on the checkout's root directory.

If opt->filename is not NULL or empty, this functions runs the given path through fsl_ckout_filename_check() and will fail if that function fails, propagating any error from that function. Ergo, opt->filename must refer to a path within the current checkout.

See also
fsl_checkin_enqueue()
fsl_checkin_is_enqueued()
fsl_checkin_discard()
fsl_checkin_commit()

References FSL_EXPORT.

◆ fsl_checkin_discard()

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_enqueue() and tags added via fsl_checkin_T_add().

See also
fsl_checkin_enqueue()
fsl_checkin_dequeue()
fsl_checkin_is_enqueued()
fsl_checkin_commit()
fsl_checkin_T_add()

References FSL_EXPORT.

◆ fsl_checkin_enqueue()

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 commit (see fsl_checkin_commit()).

Warning: if this function is not called before fsl_checkin_commit(), then fsl_checkin_commit() will select all modified, fsl_ckout_manage()'d, fsl_ckout_unmanage()'d, or renamed files by default.

opt->filename must be a non-empty NUL-terminated string. The filename is canonicalized via fsl_ckout_filename_check() - see that function for the meaning of the opt->relativeToCwd parameter. To queue all modified files in a checkout, set opt->filename to ".", opt->relativeToCwd to false, and opt->onlyModifiedFiles to true. "Modified" includes any which are pending deletion, are newly-added, or for which a rename is pending.

The resolved name must refer to either a single vfile.pathname value in the current vfile table or to a checkout-root-relative directory. All matching filenames which refer to modified files (as recorded in the vfile table) are queued up for the next commit. If opt->filename is NULL, empty, or ("." and opt->relativeToCwd is false) then all files in the vfile table are checked for changes.

If opt->scanForChanges is true then fsl_vfile_changes_scan() is called before starting to ensure that the vfile entries are up to date. If the client app has "recently" run that (or its equivalent), that (slow) step can be skipped by setting opt->scanForChanges to false before calling this

Note that after this returns, any given file may still be modified by the client before the commit takes place, and the changes on disk at the point of the fsl_checkin_commit() are the ones which get saved (or not).

For each resolved entry which actually gets enqueued (i.e. was not already enqueued and which is marked as modified), opt->callback (if it is not NULL) is passed the checkout-relative file name and the opt->callbackState pointer.

Returns 0 on success, FSL_RC_MISUSE if either pointer is NULL, or zName is NUL. Returns FSL_RC_OOM on allocation error. It is not inherently an error for opt->filename to resolve to no queue-able entries. A client can check for that case, if needed, by assigning opt->callback and incrementing a counter in that callback. If the callback is never called, no queue-able entries were found.

On error f's error state might (depending on the nature of the problem) contain more details.

See also
fsl_checkin_is_enqueued()
fsl_checkin_dequeue()
fsl_checkin_discard()
fsl_checkin_commit()

References FSL_EXPORT.

◆ fsl_checkin_is_enqueued()

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.

If NO files are in the current selection queue then this routine assumes that ALL files are implicitely selected. As long as at least one file is enqueued (via fsl_checkin_enqueue()) then this function only returns true for files which have been explicitly enqueued.

If relativeToCwd then zName is resolved based on the current directory, otherwise it assumed to be related to the checkout's root directory.

This function returning true does not necessarily indicate that the file will be checked in at the next commit. If the file has not been modified at commit-time then it will not be part of the commit.

This function honors the fsl_cx_is_case_sensitive() setting when comparing names.

Achtung: this does not resolve directory names like fsl_checkin_enqueue() and fsl_checkin_dequeue() do. It only works with file names.

Results are undefined if f is NULL.

See also
fsl_checkin_enqueue()
fsl_checkin_dequeue()
fsl_checkin_discard()
fsl_checkin_commit()

References FSL_EXPORT.

◆ fsl_checkin_T_add()

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.

Returns 0 on success, non-0 on error. A checkin may, in principal, have any number of tags, and this may be called any number of times to add new tags to the pending commit. This list of tags gets cleared by a successful fsl_checkin_commit() or by fsl_checkin_discard(). Decks require that each tag be distinct from each other (none may compare equivalent), but that check is delayed until the deck is output into its final artifact form.

See also
fsl_checkin_enqueue()
fsl_checkin_dequeue()
fsl_checkin_commit()
fsl_checkin_discard()
fsl_checkin_T_add2()

References FSL_EXPORT.

◆ fsl_checkin_T_add2()

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 object.

On success ownership of t is passed to mf. On error (see fsl_deck_T_add()) ownership is not modified.

Results are undefined if either argument is NULL or improperly initialized.

References FSL_EXPORT.

◆ fsl_ckout_calc_update_version()

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 current checkout's branch.

On success, 0 is returned and *outRid is set to the calculated RID, which may be 0, indicating that no errors were encountered but no version could be calculated.

On error, non-0 is returned, outRid is not modified, and f's error state is updated.

Returns FSL_RC_NOT_A_CKOUT if f has no checkout opened and FSL_RC_NOT_A_REPO if no repo is opened.

If it calculates that there are multiple viable descendants it returns FSL_RC_AMBIGUOUS and f's error state will contain a list of the UUIDs (or UUID prefixes) of those descendants.

Sidebar: to get the absolute latest version, irrespective of the branch, use fsl_sym_to_rid() to resolve the symbolic name "tip".

References FSL_EXPORT.

◆ fsl_ckout_changes_scan()

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).

See also
fsl_ckout_changes_visit()
fsl_vfile_changes_scan()

References FSL_EXPORT.

◆ fsl_ckout_changes_visit()

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 negative).

For each change detected it calls visitor(state,...) to report the change. If visitor() returns non-0, that code is returned from this function. If doChangeScan is true then fsl_ckout_changes_scan() is called by this function before iterating, otherwise it is assumed that the caller has called that or has otherwise ensured that the checkout db's vfile table has been populated.

If the callback returns FSL_RC_BREAK, this function stops iteration and returns 0.

Returns 0 on success.

See also
fsl_ckout_changes_scan()

References FSL_EXPORT.

◆ fsl_ckout_clear_db()

FSL_EXPORT int fsl_ckout_clear_db ( fsl_cx * f)

Clears all contents from f's checkout database, including the vfile table, vmerge table, and some of the vvar table.

The tables are left intact. Returns 0 on success, non-0 if f has no checkout or for a database error.

References FSL_EXPORT.

◆ fsl_ckout_db_search()

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 database file named one of (FOSSIL, .fslckout).

If it finds one, it returns 0 and appends the file's path to pOut if pOut is not 0. If neither is found AND if checkParentDirs is true an then it moves up the path one directory and tries again, until it hits the root of the dirPath (see below for a note/caveat).

If dirName is NULL then it behaves as if it had been passed the absolute path of the current directory (as determined by fsl_getcwd()).

This function does no normalization of dirName. Because of that...

Achtung: if dirName is relative, this routine might not find a checkout where it would find one if given an absolute path (because it traverses the path string given it instead of its canonical form). Whether this is a bug or a feature is not yet clear. When in doubt, use fsl_file_canonical_name() to normalize the directory name before passing it in here. If it turns out that we always want that behaviour, this routine will be modified to canonicalize the name.

This routine can return at least the following error codes:

  • FSL_RC_NOT_FOUND: either no checkout db was found or the given directory was not found.
  • FSL_RC_RANGE if dirName is an empty string. (We could arguably interpret this as a NULL string, i.e. the current directory.)
  • FSL_RC_OOM if allocation of a filename buffer fails.

TODO?

  • Why was the decision made not to canonicalize dirName from here? We might want to change that.

References FSL_EXPORT.

◆ fsl_ckout_dbnames()

FSL_EXPORT char const ** fsl_ckout_dbnames ( void )

Returns an array of strings with the base names of valid fossil checkout databases.

The array is terminated by a NULL element.

As of this writing, and for the foreseeable future, the list is comprised of only 3 elements, {".fslckout", "_FOSSIL_", NULL}, but the order of the non-NULL elements is unspecified by the interface.

References FSL_EXPORT.

◆ fsl_ckout_file_content()

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.

If relativeToCwd then the name is resolved from the current directory, otherwise it is assumed to be relative to the checkout root or an absolute path with the checkout dir as a prefix of that path.

On success, 0 is returned and dest's gets populated with the content of the file.

On error, non-0 is returned and, depending on the error type, dest might be partially populated. f's error state will be updated to describe the error.

Results are undefined if any pointer argument is NULL.

This function currently resolves symlinks on its way to the content, but that behaviour may change in the future to reflect f's symlink preferences.

References FSL_EXPORT.

◆ fsl_ckout_filename_check()

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 zOrigName to a form suitable for use as an in-repo filename, appending the results to pOut.

If pOut is NULL, it performs its normal checking but does not write a result, other than to return 0 for success.

As a special case, if zOrigName refers to the top-level checkout directory, it resolves to either "." or "./", depending on whether zOrigName contains a trailing slash.

If relativeToCwd is true then the filename is canonicalized based on the current working directory (see fsl_getcwd()), otherwise f's current checkout directory is used as the virtual root.

If the input name contains a trailing slash, it is retained in the output sent to pOut except in the top-dir case mentioned above.

Returns 0 on success, meaning that the value appended to pOut (if not NULL) is a syntactically valid checkout-relative path.

Returns FSL_RC_RANGE if zOrigName points to a path outside of f's current checkout root.

Returns FSL_RC_NOT_A_CKOUT if f has no checkout opened.

Returns FSL_RC_MISUSE if !zOrigName, FSL_RC_OOM on an allocation error.

This function does not validate whether or not the file actually exists, only that its name is potentially valid as a filename for use in a checkout (though other, downstream rules might prohibit that, e.g. the filename "..../...." is not valid but is not seen as invalid by this function). (Reminder to self: we could run the end result through fsl_is_simple_pathname() to catch that?)

References FSL_EXPORT.

◆ fsl_ckout_fingerprint_check()

FSL_EXPORT int fsl_ckout_fingerprint_check ( fsl_cx *const f)

Performs a "fingerprint check" between f's current checkout and repository databases.

Returns 0 if either there is no checkout, no mismatch, or it is impossible to determine because the checkout is missing a fingerprint (which is legal for "older" checkout databases).

If a mismatch is found, FSL_RC_REPO_MISMATCH is returned. Returns some other non-0 code on a lower-level error (db access, OOM, etc.).

As a special case, this is a no-op for a newly-created repo, as those cannot yet have a fingerprint.

A mismatch can happen when the repository to which a checkout belongs is replaced, either with a completely different repository or a copy/clone of that same repository. Each repository copy may have differing blob.rid values, and those are what the checkout database uses to refer to repository-side data. If those RIDs change, then the checkout is left pointing to data other than what it should be.

TODO: currently the library offers no automated recovery mechanism from a mismatch, the only remedy being to close the checkout database, destroy it, and re-create it. fossil(1) is able, in some cases, to automatically recover from this situation.

References FSL_EXPORT.

◆ fsl_ckout_has_changes()

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), returns true, else returns false.

Note that this function does not do the filesystem scan to check for changes, but checks only the db state. Use fsl_vfile_changes_scan() to perform the actual scan (noting that library-side APIs which update that state may also record individual changes or automatically run a scan).

References FSL_EXPORT.

◆ fsl_ckout_manage()

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 to-be-added file, or updates an existing record if one exists.

This function ensures that opt->filename gets canonicalized and can be found under the checkout directory, and fails if no such file exists (checking against the canonicalized name). Filenames are all filtered through fsl_reserved_fn_check() and may have other filters applied to them, as determined by the options object.

Each filename which passes through the filters is passed to the opt->callback (if not NULL), which may perform a final filtering check and/or alert the client about the file being queued.

The options object is non-const because this routine updates opt->counts when it adds, updates, or skips a file. On each call, it updated opt->counts without resetting it (as this function is typically called in a loop). This function does not modify any other entries of that object and it requires that the object not be modified (e.g. via opt->callback()) while it is recursively processing. To reset the counts between calls, if needed:

opt->counts = fsl_ckout_manage_opt_empty.counts;
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

Returns 0 on success, non-0 on error.

Files queued for addition this way can be unqueued before they are committed using fsl_ckout_unmanage().

To avoid Significant Grief, this routine automatically skips any directories under opt->filename which appear to be fossil checkout roots unless that directory is f's current checkout directory, into which it will recurse normally.

See also
fsl_ckout_unmanage()
fsl_reserved_fn_check()

References FSL_EXPORT.

◆ fsl_ckout_manifest_setting()

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 a checkout directory, as specified by the repository's 'manifest' configuration setting, and sets *m to a bitmask indicating which of those are enabled.

It first checks for a versioned setting then, if no versioned setting is found, a repository-level setting.

A truthy setting value (1, "on", "true") means to write the manifest and manifest.uuid files. A string with any of the letters 'r', 'u', or 't' means to write the [r]aw, [u]uid, and/or [t]ags file(s), respectively.

If the manifest setting is falsy or not set, *m is set to 0, else m is set to a bitmask representing which file(s) are considered to be auto-generated for this repository:

  • FSL_MANIFEST_MAIN = manifest
  • FSL_MANIFEST_UUID = manifest.uuid
  • FSL_MANIFEST_TAGS = manifest.tags

Any db-related or allocation errors while trying to fetch the setting are silently ignored.

For performance's sake, since this is potentially called often from fsl_reserved_fn_check(), this setting is currently cached by this routine (in the fsl_cx object), but that ignores the fact that the manifest setting can be modified at any time, either in a versioned setting file or the repository db, and may be modified from outside the library. There's a tiny back-door for working around that: if m is NULL, the cache will be flushed and no other work will be performed. Thus the following approach can be used to force a fresh check for that setting:

fsl_ckout_manifest_setting(f, NULL); // clears caches, does nothing else
fsl_ckout_manifest_setting(f, &myInt); // loads/caches the setting
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...

References FSL_EXPORT.

◆ fsl_ckout_manifest_write()

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 the the checkout's root directory.

The 2nd-4th arguments are interpreted as follows:

0: Do not write that file.

>0: Always write that file.

<0: Use the value of the "manifest" config setting (see fsl_ckout_manifest_setting()) to determine whether or not to write that file.

As each file is written, its mtime is set to that of the checkout version. (Forewarning: that behaviour may change if it proves to be problematic vis a vis build processes.)

Returns 0 on success, non-0 on error:

  • FSL_RC_NOT_A_CKOUT if no checkout is opened.
  • FSL_RC_RANGE if the current checkout RID is 0 (indicating a fresh, empty repository).
  • Various potential DB/IO-related error codes.

If the final argument is not NULL then it will be updated to contain a bitmask representing which files, if any, were written: see fsl_ckout_manifest_setting() for the values. It is updated regardless of success or failure and will indicate which file(s) was/were written before the error was triggered.

Each file implied by the various manifest settings which is NOT written by this routine and is also not part of the current checkout (i.e. not listed in the vfile table) will be removed from disk, but a failure while attempting to do so will be silently ignored.

See also
fsl_repo_manifest_write()

References FSL_EXPORT.

◆ fsl_ckout_merge()

FSL_EXPORT int fsl_ckout_merge ( fsl_cx *const f,
fsl_merge_opt const *const opt )

UNDER CONSTRUCTION and not yet well-tested.

Performs a "merge" operation on the current checkout, merging in version opt->mergeRid. If that version has already been merged, this call has no SCM-related side effects.

Returns 0 on success, any number of non-0 codes on error, including, but not limited to:

  • FSL_RC_NOT_A_CKOUT if f has no opened checkout.
  • FSL_RC_OOM on allocation error.
  • FSL_RC_TYPE if opt->mergeRid or opt->baselineRid do to refer to a checkin.
  • FSL_RC_PHANTOM if a file participating in the merge is a phantom.
  • FSL_RC_RANGE if the to-be-merged-in RID is the same as the current checkout RID or the same as the pivot/baseline of the merge.
  • FSL_RC_NOT_FOUND if no common ancestor can be found for use as a basis for the merge.
  • FSL_RC_MISUSE if the current checkout is empty (has an RID of 0).
  • Any number of DB- or I/O-related codes, as well as codes from underlying APIs such as fsl_vfile_changes_scan().

For all but the most trivial argument validation errors or allocation errors, f's error state will be updated with a description of the problem.

TODOs and potential TODOs:

  • There are certain illegal combinations of merge state which may require adding new result codes for. e.g. a no-op merge.
  • Empty directories may be left behind when a merge removes all files in a directory. fsl_ckout_update() handles that case but fsl_ckout_merge() currently does not.

References FSL_EXPORT.

◆ fsl_ckout_open_dir()

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).

This routine canonicalizes its dirName argument using fsl_file_canonical_name(), then passes that and checkParentDirs on to fsl_ckout_db_search() to find a checkout db, so see that routine for how it searches.

If this routine finds/opens a checkout, it also tries to open the repository database from which the checkout derives, and fails if it cannot. The library never allows a checkout to be opened without its corresponding repository partner because a checkout has hard dependencies on the repo's state.

Returns 0 on success. If there is an error opening or validating the checkout or its repository db, f's error state will be updated. Error codes/conditions include:

  • FSL_RC_MISUSE if f is NULL.
  • FSL_RC_ACCESS if f already has and opened checkout.
  • FSL_RC_OOM if an allocation fails.
  • FSL_RC_NOT_FOUND if no checkout is foud or if a checkout's repository is not found.
  • FSL_RC_RANGE if dirname is not NULL but has a length of 0.
  • Various codes from fsl_getcwd() (if dirName is NULL).
  • Various codes if opening the associated repository DB fails.

TODO: there's really nothing in the architecture which restricts a checkout db to being in the same directory as the checkout, except for some historical bits which "could" be refactored. It "might be interesting" to eventually provide a variant which opens a checkout db file directly. We have the infrastructure, just need some refactoring. It "shouldn't" require any trickery or incompatibilities with fossil(1).

References FSL_EXPORT.

◆ fsl_ckout_rename()

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 within the current checkout.

This updates the current checkout's vfile table with the changes, and optionally attempts to move the files within the filesystem, but does not commit anything, so the change may still be reverted later on.

If an entry in opt->src matches an existing directory name within the SCM-managed file list, this function assumes that all files under that directory are to be moved.

If opt->relativeToCwd is true then the destination name and all opt->src names are canonicalized based on the current working directory (see fsl_getcwd()), otherwise they are assumed to be relative to f's current checkout directory.

If opt->dest refers to an existing directory, when an opt->src entry refers to a directory then that whole directory, including the directory name part, is renamed. If opt->dest does not exist in the filesystem and if opt->src resolves to multiple inputs, opt->dest is assumed to be a new target directory but the renaming behavior of the opt->src files differs. Examples:

  • Case 1: opt->dest refers to an existing directory: moving directory foo/bar to baz will result in baz/bar.
  • Case 2: opt->dest does not refer to an existing directory: moving directory foo/bar to baz results in baz with the previous contents of foo/bar.

Why? Because that's how fossil(1) does it.

This function matches opt->src entries only against vfile.pathname, not vfile.origname.

If opt->doFsMv is true then the final operation this function attempts is to rename source files to their new destination. It will only attempt this in cases where (A) the original file exists and (B) the destination file does not exist. Any errors generated during this filesystem-level rename/move step are ignored for two reasons: 1) fossil(1) does it that way and (2) after moving any files, trying to roll back and undo the filesystem-level operations would add a significant amount of complexity and new errror cases (what happens when a try-to-undo-rename fails?).

Returns 0 on succcess. Potential errors include:

  • FSL_RC_OOM on allocation error.
  • FSL_RC_NOT_A_CKOUT if f has no opened checkout.
  • FSL_RC_MISUSE: opt->src contains multiple entries but the destination is not an existing directory.
  • FSL_RC_ALREADY_EXISTS: cannot rename because the destination name is already in use by another record.
  • FSL_RC_TYPE: opt->dest refers to a non-directory and an opt->src entry refers to a directory.
  • Any potential DB-related errors.

BUGS/Shortcomings:

  • If it fails moving files in the filesystem, it might have successfully already moved one or more source files, and those moves are not undone.
  • Depending on the case-sensitivity of the repo and the filesystem, it might (UNTESTED) fail to rename a file if the new name differs only in its case (e.g. README.TXT to README.txt). Those relavant code renames such vfile entries but leaves the filesystem entries intact because fossil(1) does it that way.
  • If it moves a whole directory full of files it leaves any original directories intact. Improving this is on the TODO list. Often, such directories have contents (e.g. compiled/generated/temp files) and cannot be removed.

References FSL_EXPORT.

◆ fsl_ckout_rename_revert()

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().

zNewName is the current (renamed) name of the file.

If relativeToCwd is true then zNewName is canonicalized based on the current working directory (see fsl_getcwd()), otherwise it is assumed to be relative to f's current checkout directory.

On success, or if no such pending rename is found, it returns 0. If it actually performs a db-level rename then it sets *didSomething to true if didSomething is not NULL. It should arguably return FSL_RC_NOT_FOUND (or some such) if no matching rename is pending, but that currently feels overly-pedantic.

If doFsMv is true and a db entry is renamed and a file with the new name exists in the filesystem then this function will delete any file which has the original name and rename the zNewName file to its reverted name. If that fails, the operation as a whole will fail and the db changes will be rolled back. Note, however, that a file deleted by this operation cannot be recovered and that the deletion must be done before the rename is attempted.

On error, returns any of a wide array of non-0 result codes, only two of which can come directly from this function: FSL_RC_OOM or FSL_RC_NOT_A_CKOUT. Any other non-zero result codes are propagated errors from lower-level code.

References FSL_EXPORT.

◆ fsl_ckout_revert()

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 version.

If zFilename refers to a directory, all managed files under that directory are reverted (if modified). If zFilename is NULL or empty, all modifications in the current checkout are reverted.

If a file has been added but not yet committed, the add is un-queued but the file is otherwise untouched. If the file has been queued for removal, this removes it from that queue as well as restores its contents.

If a rename is pending for the given filename, the name may match either its original name or new name. Whether or not that will actually work when file A is renamed to B and file C is renamed to A is anyone's guess. (Noting that (fossil mv) won't allow that situation to exist in the vfile table for a single checkout version, so it seems safe enough.)

If the 4th argument is not NULL then it is called for each revert (after the revert happens) to report what was done with that file. It gets passed the checkout-relative name of each reverted file. The 5th argument is not interpreted by this function but is passed on as-is as the final argument to the callback. If the callback returns non-0, the revert process is cancelled, any pending transaction is set to roll back, and that error code is returned. Note that cancelling a revert mid-process will leave file changes made by the revert so far in place, and thus the checkout db and filesystem will be in an inconsistent state until fsl_vfile_changes_scan() (or equivalent) is called to restore balance to the world.

Files which are not actually reverted because their contents or permissions were not modified on disk are not reported to the callback unless the reversion was the un-queuing of an ADD or REMOVE operation.

Returns 0 on success, any number of non-0 results on error.

[tag:bug:revert-merge-hiccup] (2024-09-13): it is possible, via merging and copying modified files between multiple checkouts of the same repo, to get the tree into a state where this function has no files to revert and therefore does not clear the merge state. This condition is very tricky to trigger, and has only been seen once in the wild. "The problem" with fixing that is that whether or not we need to do a full wipe of the merge state (as opposed to just wiping merge state of individual files) depends largely on information which (A) this function does have and (B) is onerous for the caller to figure out and provide (namely, whether it's a full revert or not). As this bug is so rare, we'll leave it for now and ponder potential solutions. As of 2024-09-13, this bug is believed to have been adequately resolved, but exactly how it was initially triggered is unclear, so we don't have a test which proves it is resolved.

References FSL_EXPORT.

◆ fsl_ckout_unmanage()

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.

Unlike fsl_ckout_manage(), this routine does not ensure that opt->filename actually exists - it only normalizes zFilename into its repository-friendly form and passes it through the vfile table.

If opt->filename refers to a directory then this operation queues all files under that directory (recursively) for removal. In this case, it is irrelevant whether or not opt->filename ends in a trailing slash.

Returns 0 on success, any of a number of non-0 codes on error. Returns FSL_RC_MISUSE if !opt->filename or !*opt->filename. Returns FSL_RC_NOT_A_CKOUT if f has no opened checkout.

If opt->callback is not NULL, it is called for each newly-unamanaged entry. The intention is to provide it the opportunity to notify the user, record the filename for later use, remove the file from the filesystem, etc. If it returns non-0, the unmanaging process will fail with that code and any pending transaction will be placed into a rollback state.

This routine does not actually remove any files from the filesystem, it only modifies the vfile table entry so that the file(s) will be removed from the SCM by the commit process. If opt->filename is an entry which was previously fsl_ckout_manage()'d, but not yet committed, or any such entries are found under directory opt->filename, they are removed from the vfile table. i.e. this effective undoes the add operation.

See also
fsl_ckout_manage()

References FSL_EXPORT.

◆ fsl_ckout_update()

FSL_EXPORT int fsl_ckout_update ( fsl_cx * f,
fsl_ckup_opt const * opt )

UNDER CONSTRUCTION.

Performs an "update" operation on f's currenly-opened checkout. Performing an update is similar to performing a checkout, the primary difference being that an update will merge local file modifications into any newly-updated files, whereas a checkout will overwrite them.

TODO?: fossil(1)'s update permits a list of files, in which case it behaves differently: it updates the given files to the version requested but leaves the checkout at its current version. To be able to implement that we either need clients to call this in a loop, changing opt->filename on each call (like how we do fsl_ckout_manage()) or we need a way for them to pass on the list of files/dir in the opt object.

See also
fsl_repo_ckout().

References FSL_EXPORT.

◆ fsl_ckout_version_info()

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.

If f has an opened checkout then...

If uuid is not NULL then *uuid is set to the UUID of the opened checkout, or NULL if there is no checkout. If rid is not NULL, *rid is set to the record ID of that checkout, or 0 if there is no checkout (or the current checkout is from an empty repository). The returned uuid bytes and rid are owned by f and valid until the library updates its checkout state to a newer checkout version (essentially unpredictably). When in doubt about lifetime issues, copy the UUID immediately after calling this if they will be needed later.

Corner case: a new repo with no checkins has an RID of 0 and a UUID of NULL. That does not happen with fossil-generated repositories, as those always "seed" the database with an initial commit artifact containing no files.

References FSL_EXPORT.

◆ fsl_ckout_vfile_ids()

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 that routine.

This routine works exactly like that one except for the following differences:

1) The given filename and the relativeToCwd arguments are passed to by fsl_ckout_filename_check() to canonicalize the name and ensure that it points to someplace within f's current checkout.

2) Directory names passed to it may optionally end in an trailing slash.

3) Because of (1), zName may not be NULL or empty. To fetch all of the vfile IDs for the current checkout, pass a zName of "." and relativeToCwd=false.

Returns 0 on success, else:

  • FSL_RC_MISUSE if zName is NULL or empty.
  • FSL_RC_OOM on allocation error.
  • FSL_RC_NOT_A_CKOUT if f has no opened checkout.
  • FSL_RC_RANGE if the given name points outside of the checkout.

References FSL_EXPORT.

◆ fsl_filename_to_vfile_id()

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 vfile.vid == vid.

If vid<=0 then the current checkout RID is used. This function does not do any path resolution or normalization on zName and checks only for an exact match (honoring f's case-sensitivity setting - see fsl_cx_case_sensitive_set()).

On success it returns 0 and assigns *vfid to the vfile.id value of the matching file. If no match is found, 0 is returned and *vfile is set to 0. Returns FSL_RC_NOT_A_CKOUT if no checkout is opened, FSL_RC_RANGE if zName is not a simple path (see fsl_is_simple_pathname()), and any number of codes for db-related errors.

This function matches only vfile.pathname, not vfile.origname, because it is possible for a given name to be in both fields (in different records) at the same time.

References FSL_EXPORT.

◆ fsl_filename_to_vfile_ids()

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 found under a subdirectory named zName (with no trailing slash).

zName must be relative to the checkout root. As a special case, if zName is NULL, empty, or "." then all files in vfile with the given vid are selected. For each entry it finds, it adds the vfile.id to dest. If vid<=0 then the current checkout RID is used.

If changedOnly is true then only entries which have been marked in the vfile table as having some sort of change are included, so if true then fsl_ckout_changes_scan() (or equivalent) must have been "recently" called to ensure that state is up to do. This routine only checks the vfile table for "is changed" state, it does not do filesystem-level checks on the files.

This search honors the context-level case-sensitivity setting (see fsl_cx_case_sensitive_set()).

Returns 0 on success. Not finding anything is not treated as an error, though we could arguably return FSL_RC_NOT_FOUND for the cases which use this function. In order to determine whether or not any results were actually found, compare dest->entryCount before and after calling this.

This function matches only vfile.pathname, not vfile.origname, because it is possible for a given name to be in both fields (in different records) at the same time.

See also
fsl_ckout_vfile_ids()

References FSL_EXPORT.

◆ fsl_is_rooted_in_ckout()

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, else false.

As a special case, it returns false if the path is the checkout root unless zAbsPath has a trailing slash. (The checkout root is always stored with a trailing slash because that simplifies its internal usage.)

Note that this is strictly a string comparison, not a filesystem-level operation.

References FSL_EXPORT.

◆ fsl_is_rooted_in_ckout2()

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 a description of the problem and returns non-0: FSL_RC_RANGE or (if updating the error state fails) FSL_RC_OOM.

References FSL_EXPORT.

◆ fsl_is_top_of_ckout()

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 that only a cursory check is done - the db is not opened and validated), the name of that database file (minus the directory part) is returned, else NULL is returned.

The returned bytes are static.

See also
fsl_ckout_dbnames()

References FSL_EXPORT.

◆ fsl_preferred_ckout_db_name()

FSL_EXPORT char const * fsl_preferred_ckout_db_name ( void )

Returns the base name of the current platform's checkout database file.

That is "_FOSSIL_" on Windows and ".fslckout" everywhere else. The returned bytes are static.

TODO: an API which takes a dir name and looks for either name

References FSL_EXPORT.

◆ fsl_repo_ckout()

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->checkinRid to the root directory of f's currently-opened checkout.

i.e. it performs a "checkout" operation.

For each extracted entry, cOpt->callback (if not NULL) will be passed a (fsl_ckup_state const*) which contains a pointer to the fsl_repo_extract_state and some additional metadata regarding the extraction. The value of cOpt->callbackState will be set as the callbackState member of that fsl_ckup_state struct, so that the client has a way of passing around app-specific state to that callback.

After successful completion, the process will report (see below) any files which were part of the previous checkout version but are not part of the current version, optionally removing them from the filesystem (depending on the value of opt->rmMissingPolicy). It will IGNORE ANY DELETION FAILURE of files it attempts to delete. The reason it does not fail on removal error is because doing so would require rolling back the transaction, effectively undoing the checkout, but it cannot roll back any prior deletions which succeeded. Similarly, after all file removal is complete, it attempts to remove any now-empty directories left over by that process, also silently ignoring any errors. If the cOpt->dryRun option is specified, it will "go through the motions" of removing files but will not actually attempt filesystem removal. For purposes of the callback, however, it will report deletions as having happened (but will also set the dryRun flag on the object passed to the callback).

After unpacking the SCM-side files, it may write out one or more manifest files, as described for fsl_ckout_manifest_write(), if the 'manifest' config setting says to do so.

As part of the file-removal process, AFTER all "existing" files are processed, it calls cOpt->callback() (if not NULL) for each removed file, noting the following peculiarities in the fsl_ckup_state object which is passed to it for those calls:

  • It is called after the processing of "existing" files. Thus the file names passed during this step may appear "out of order" with regards to the others (which are guaranteed to be passed in lexical order, though whether it is case-sensitive or not depends on the repository's case-sensitivity setting).
  • fileRmInfo will indicate that the file was removed from the checkout, and whether it was actually removed or retained in the filesystem. This will indicate filesystem-level removal even when in dry-run mode, though in that case no filesystem-level removal is actually attempted.
  • extractState->fileRid will refer to the file's blob's RID for the previous checkout version.
  • extractState->content will be NULL.
  • extractState->callbackState will be NULL.
  • extractState->fCard will refer to the pre-removal state of the file. i.e. the state as it was in the checkout prior to this function being called.

Returns 0 on success. Returns FSL_RC_NOT_A_REPO if f has no opened repo, FSL_RC_NOT_A_CKOUT if no checkout is opened. If cOpt->callback is not NULL and returns a non-0 result code, extraction ends and that result is returned. If it returns non-0 at any point after basic argument validation, it rolls back all changes or sets the current transaction stack into a rollback state.

See also
fsl_repo_open_ckout()

References FSL_EXPORT.

◆ fsl_repo_open_ckout()

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.

If opening an existing one, it gets "stolen" from any repository it might have been previously mapped to.

  • Requires that f have an opened repository db and no opened checkout. Returns FSL_RC_NOT_A_REPO if no repo is opened and FSL_RC_MISUSE if a checkout is opened.
  • Creates/re-uses a .fslckout DB in the dir opt->targetDir. The directory must be NULL or already exist, else FSL_RC_NOT_FOUND is returned. If opt->dbOverwritePolicy is false then it fails with FSL_RC_ALREADY_EXISTS if that directory already contains a checkout db.

Note that this does not extract any SCM'd files from the repository, it only opens (and possibly creates) the checkout database.

Pending:

  • If opening an existing checkout db for a different repo then delete the STASH and UNDO entries, as they're not valid for a different repo.

References FSL_EXPORT.

◆ fsl_vfile_changes_scan()

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 ID then compares files listed in it against files in the checkout directory, updating vfile's status for the current checkout version id as its goes.

If vid is<=0 then the current checkout's RID is used in its place (note that 0 is the RID of an initial empty repository!).

cksigFlags must be 0 or a bitmask of fsl_ckout_sig_e values.

This is a relatively memory- and filesystem-intensive operation, and should not be performed more often than necessary. Many SCM algorithms rely on its state being correct, however, so it's generally better to err on the side of running it once too often rather than once too few times.

Returns 0 on success, non-0 on error.

BUG: this does not properly catch one particular corner-case change, where a file has been replaced by a same-named non-file (symlink or directory).

References FSL_EXPORT.

◆ fsl_vfile_load()

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 checkin manifest.

If manifestRid is 0 or less then the current checkout's RID is used. If vfile already contains any content for the given checkin, it is left intact (and several processes rely on that behavior to keep it from nuking, e.g., as-yet-uncommitted queued add/rm entries).

Returns 0 on success, any number of codes on any of many potential errors.

f must not be NULL and must have opened checkout and repository databases. In debug builds it will assert that that is so.

If the 3rd argument is true, any entries in vfile for checkin versions other than the one specified in the 2nd argument are cleared from the vfile table. That is almost always the desired behavior, but there are rare cases where vfile needs to temporarily (for the duration of a single transaction) hold state for multiple versions.

If the 4th argument is not NULL, it gets assigned the number of blobs from the given version which are currently missing from the repository due to being phantoms (as opposed to being shunned).

Returns 0 on success, FSL_RC_NOT_A_CKOUT if no checkout is opened, FSL_RC_OOM on allocation error, FSL_RC_DB for db-related problems, et.al.

Misc. notes:

  • This does NOT update the "checkout" vvar table entry because this routine is sometimes used in contexts where we need to briefly maintain two vfile versions and keep the previous checkout version.
  • Apps must take care to not leave more than one version in the vfile table for longer than absolutely needed. They "really should" use fsl_vfile_unload() to clear out any version they load with this routine.
See also
fsl_vfile_unload()
fsl_vfile_unload_except()

References FSL_EXPORT.

◆ fsl_vfile_pathname()

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.

Results are undefined if f does not have an opened checkout. On success returns 0 and sets *zOut to the name, transfering ownership to the caller (who must eventually pass it to fsl_free()). If absolute is true then the returned name has the checkout dir prepended to it, else it is relative to the top of the repo.

Potential TODO: this routine is in no way optimized for heavy use within an app, expecting to be only rarely used, e.g. in conjunction with fsl_ckout_rename()-like ops. If it sees any significant use it should be refactored to use a cached statement.

References FSL_EXPORT.

◆ fsl_vfile_unload()

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.vid value.

If vid<=0 then the current checkout RID is used (which is never a good idea from client-side code!).

ACHTUNG: never do this without understanding the consequences. It can ruin the current checkout state.

Returns 0 on success, FSL_RC_NOT_A_CKOUT if f has no checkout opened, FSL_RC_DB on any sort of db-related error (in which case f's error state is updated with a description of the problem).

See also
fsl_vfile_load()
fsl_vfile_unload_except()

References FSL_EXPORT.

◆ fsl_vfile_unload_except()

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 vid.

If vid is <=0 then the current checkout RID is used.

Returns 0 on success, FSL_RC_NOT_A_CKOUT if f has no checkout opened, FSL_RC_DB on any sort of db-related error (in which case f's error state is updated with a description of the problem).

See also
fsl_vfile_load()
fsl_vfile_unload()

References FSL_EXPORT.

Variable Documentation

◆ fsl_checkin_opt_empty

FSL_EXPORT const fsl_checkin_opt fsl_checkin_opt_empty

Empty-initialized fsl_checkin_opt instance, intended for use in copy-constructing.

It is important that clients copy this value (or fsl_checkin_opt_empty_m) to cleanly initialize their fsl_checkin_opt instances, as this may set default values which (e.g.) a memset() would not.

Definition at line 1283 of file checkout.h.

◆ fsl_checkin_queue_opt_empty

const fsl_checkin_queue_opt fsl_checkin_queue_opt_empty
extern

Initialized-with-defaults fsl_checkin_queue_opt structure, intended for non-const copy initialization.

◆ fsl_ckout_manage_opt_empty

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 initialization.

Definition at line 354 of file checkout.h.

◆ fsl_ckout_rename_opt_empty

const fsl_ckout_rename_opt fsl_ckout_rename_opt_empty
extern

Initialized-with-defaults fsl_ckout_rename_opt structure, intended for non-const copy initialization.

◆ fsl_ckout_revert_opt_empty

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 initialization.

Definition at line 2222 of file checkout.h.

◆ fsl_ckout_unmanage_opt_empty

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 initialization.

Definition at line 525 of file checkout.h.

◆ fsl_ckup_opt_empty

FSL_EXPORT const fsl_ckup_opt fsl_ckup_opt_empty

Empty-initialised fsl_ckup_opt instance.

Clients should copy this value (or fsl_ckup_opt_empty_m) to initialise fsl_ckup_opt instances for sane default values.

Definition at line 1867 of file checkout.h.

◆ fsl_merge_opt_empty

const fsl_merge_opt fsl_merge_opt_empty
extern

Initialized-with-defaults fsl_merge_opt structure, intended for non-const copy initialization.

◆ fsl_repo_open_ckout_opt_empty

FSL_EXPORT const fsl_repo_open_ckout_opt fsl_repo_open_ckout_opt_empty

Empty-initialised fsl_repo_open_ckout_opt instance.

Clients should copy this value (or fsl_repo_open_ckout_opt_empty_m) to initialise fsl_repo_open_ckout_opt instances for sane default values.

Definition at line 1533 of file checkout.h.