libfossil
fsl_checkin_opt Struct Reference

Parameters for fsl_checkin_commit(). More...

#include "checkout.h"

Collaboration diagram for fsl_checkin_opt:

Data Fields

bool allowMergeConflict
 If true, allow a file to be checked in if it contains fossil-style merge conflict markers, else fail if an attempt is made to commit any files with such markers.
char const * bgColor
 If this->branch is not NULL, this is applied as its "bgcolor" propagating property.
char const * branch
 If not NULL, makes the checkin the start of a new branch with this name.
bool calcRCard
 Whether or not to calculate an R-card.
char const * closeBranch
 If this is not NULL then the committed manifest will include a tag which closes the branch.
int deltaPolicy
 Whether to allow (or try to force) a delta manifest or not.
bool dryRun
 If true, the checkin's db savepoint is rolled back after it's complete, effectively meaning that the checkin does not take place (but all of the work involved happens).
char const * dumpManifestFile
 Tells fsl_checkin_commit() to dump the generated manifest to this file.
bool integrate
 Tells the checkin to close merged-in branches (merge type of 0).
bool isPrivate
 If true, the checkin will be marked as private, otherwise it will be marked as private or public, depending on whether or not it inherits private content.
double julianTime
 Time of the checkin.
char const * message
 The commit message.
char const * messageMimeType
 The optional mime type for the message.
bool rmRemovedFiles
 NOT YET IMPLEMENTED!
bool scanForChanges
 A hint to fsl_checkin_commit() about whether it needs to scan the checkout for changes.
char const * user
 The user name for the checkin.

Detailed Description

Parameters for fsl_checkin_commit().

Checkins are created in a multi-step process:

  • fsl_checkin_enqueue() queues up a file or directory for commit at the next commit.
  • fsl_checkin_dequeue() removes an entry, allowing UIs to toggle files in and out of a checkin before committing it.
  • fsl_checkin_is_enqueued() can be used to determine whether a given name is already enqueued or not.
  • fsl_checkin_T_add() can be used to T-cards (tags) to a deck. Branch tags are intended to be applied via the fsl_checkin_opt::branch member.
  • fsl_checkin_discard() can be used to cancel any pending file enqueuings, effectively cancelling a commit (which can be re-started by enqueuing another file).
  • fsl_checkin_commit() creates a checkin for the list of enqueued files (defaulting to all modified files in the checkout!). It takes an object of this type to specify a variety of parameters for the check.

Note that this API uses the terms "enqueue" and "unqueue" rather than "add" and "remove" because those both have very specific (and much different) meanings in the overall SCM scheme.

Definition at line 1074 of file checkout.h.

Field Documentation

◆ allowMergeConflict

bool fsl_checkin_opt::allowMergeConflict

If true, allow a file to be checked in if it contains fossil-style merge conflict markers, else fail if an attempt is made to commit any files with such markers.

Definition at line 1142 of file checkout.h.

◆ bgColor

char const* fsl_checkin_opt::bgColor

If this->branch is not NULL, this is applied as its "bgcolor" propagating property.

If this->branch is NULL then this is applied as a one-time color tag to the checkin.

It must be NULL, empty, or in a form usable by HTML/CSS, preferably #RRGGBB form. Length-0 values are ignored (as if they were NULL).

Definition at line 1109 of file checkout.h.

◆ branch

char const* fsl_checkin_opt::branch

If not NULL, makes the checkin the start of a new branch with this name.

Definition at line 1098 of file checkout.h.

◆ calcRCard

bool fsl_checkin_opt::calcRCard

Whether or not to calculate an R-card.

Doing so is very expensive (memory and I/O) but it adds another layer of consistency checking to manifest files. In practice, the R-card is somewhat superfluous and the cost of calculating it has proven painful on very large repositories. fossil(1) creates an R-card for all checkins but does not require that one be set when it reads a manifest.

Definition at line 1127 of file checkout.h.

◆ closeBranch

char const* fsl_checkin_opt::closeBranch

If this is not NULL then the committed manifest will include a tag which closes the branch.

The value of this string will be the value of the "closed" tag, and the value may be an empty string. The intention is that this gets set to a comment about why the branch is closed, but it is in no way mandatory.

Definition at line 1230 of file checkout.h.

◆ deltaPolicy

int fsl_checkin_opt::deltaPolicy

Whether to allow (or try to force) a delta manifest or not.

0 means no deltas allowed - it will generate a baseline manifest. Greater than 0 forces generation of a delta if possible (if one can be readily found) even if doing so would not save a notable amount of space. Less than 0 means to decide via some heuristics.

A "readily available" baseline means either the current checkout is a baseline or has a baseline. In either case, we can use that as a baseline for a delta. i.e. a baseline "should" generally be available except on the initial checkin, which has neither a parent checkin nor a baseline.

The current behaviour for "auto-detect" mode is: it will generate a delta if a baseline is "readily available" and the repository has at least one delta already. Once it calculates a delta form, it calculates whether that form saves any appreciable space/overhead compared to whether a baseline manifest was generated. If so, it discards the delta and re-generates the manifest as a baseline. The "force" behaviour (deltaPolicy>0) bypasses the "is it too big?" test, and is only intended for testing, not real-life use.

Caveat: if the repository has the "forbid-delta-manifests" set to a true value, this option is ignored: that setting takes priority. Similarly, it will not create a delta in a repository unless a delta has been "seen" in that repository before or this policy is set to >0. When a checkin is created with a delta manifest, that fact gets recorded in the repository's config table.

Note that delta manifests have some advantages and may not actually save much (if any) repository space because the lower-level delta framework already compresses parent versions of artifacts tightly. For more information see:

https://fossil-scm.org/home/doc/tip/www/delta-manifests.md

Definition at line 1215 of file checkout.h.

◆ dryRun

bool fsl_checkin_opt::dryRun

If true, the checkin's db savepoint is rolled back after it's complete, effectively meaning that the checkin does not take place (but all of the work involved happens).

This unfortunately has to put any pending transactions into pending-rollback mode, too, because of $REASONS.

Definition at line 1174 of file checkout.h.

◆ dumpManifestFile

char const* fsl_checkin_opt::dumpManifestFile

Tells fsl_checkin_commit() to dump the generated manifest to this file.

Intended only for debugging and testing. Checking in will fail if this file cannot be opened for writing.

Definition at line 1237 of file checkout.h.

◆ integrate

bool fsl_checkin_opt::integrate

Tells the checkin to close merged-in branches (merge type of 0).

INTEGRATE merges (type=-4) are always closed by a checkin. This does not apply to CHERRYPICK (type=-1) and BACKOUT (type=-2) merges.

Definition at line 1135 of file checkout.h.

◆ isPrivate

bool fsl_checkin_opt::isPrivate

If true, the checkin will be marked as private, otherwise it will be marked as private or public, depending on whether or not it inherits private content.

Definition at line 1116 of file checkout.h.

◆ julianTime

double fsl_checkin_opt::julianTime

Time of the checkin.

If 0 or less, the time of the fsl_checkin_commit() call is used.

Definition at line 1221 of file checkout.h.

◆ message

char const* fsl_checkin_opt::message

The commit message.

May not be empty - the library forbids empty checkin messages.

Definition at line 1079 of file checkout.h.

◆ messageMimeType

char const* fsl_checkin_opt::messageMimeType

The optional mime type for the message.

Only set this if you know what you're doing.

Definition at line 1085 of file checkout.h.

◆ rmRemovedFiles

bool fsl_checkin_opt::rmRemovedFiles

NOT YET IMPLEMENTED!

TODO!

If true, files which are removed from the SCM by this checkin should be removed from the filesystem.

Reminder to self: when we do this, incorporate fsl_rm_empty_dirs().

Definition at line 1165 of file checkout.h.

◆ scanForChanges

bool fsl_checkin_opt::scanForChanges

A hint to fsl_checkin_commit() about whether it needs to scan the checkout for changes.

Set this to false ONLY if the calling code calls fsl_ckout_changes_scan() (or equivalent, e.g. fsl_vfile_changes_scan()) immediately before calling fsl_checkin_commit(). fsl_checkin_commit() requires a non-stale changes scan in order to function properly, but it's a computationally slow operation so the checkin process does not want to duplicate it if the application has recently done so.

Definition at line 1154 of file checkout.h.

◆ user

char const* fsl_checkin_opt::user

The user name for the checkin.

If NULL or empty, it defaults to fsl_cx_user_get(). If that is NULL, a FSL_RC_RANGE error is triggered.

Definition at line 1092 of file checkout.h.


The documentation for this struct was generated from the following file: