300
285
that if a revision is present, everything to reconstruct it will be
307
Caller starts a commit
309
>>> Branch.commit(from_tree, options)
311
This creates a CommitBuilder object matched to the Branch, Repository and
312
Tree. It can vary depending on model differences or by knowledge of what
313
is efficient with the Repository and Tree. Model differences might
314
include whether no-text-change merges need to be reported, and whether the
316
The basic CommitBuilder.commit structure can be
318
1. Ask the branch if it is ready to commit (up to date with master if
321
2. Ask the tree if it is ready to commit to the branch (up to date with
322
branch?), no conflicts, etc
324
3. Commit changed files; prototype implementation:
326
a. Ask the working tree for all committable files; for each it should
327
return the per-file parents, stat information, kind, etc.
329
b. Ask the repository to store the new file text; the repository should
330
return the stored sha1 and new revision id.
332
4. Commit changed inventory
334
5. Commit revision object
344
288
Complications of commit
345
289
-----------------------
352
296
There are several checks that may cause the commit to be refused, which
353
297
may be activated or deactivated by options.
355
* presence of conflicts in the tree
357
* presence of unknown files
359
* the working tree basis is up to date with the branch tip
361
* the local branch is up to date with the master branch, if there
362
is one and --local is not specified
364
* an empty commit message is given,
366
* a hook flags an error
368
* a "pointless" commit, with no inventory changes
299
* presence of conflicts in the tree
301
* presence of unknown files
303
* the working tree basis is up to date with the branch tip
305
* the local branch is up to date with the master branch, if there
306
is one and --local is not specified
308
* an empty commit message is given,
310
* a hook flags an error
312
* a "pointless" commit, with no inventory changes
370
314
Most of these require walking the tree and can be easily done while
371
315
recording the tree shape. This does require that it be possible to abort
376
320
Other complications:
378
* when automatically adding new files or deleting missing files during
379
commit, they must be noted during commit and written into the working
382
* refuse "pointless" commits with no file changes - should be easy by
383
just refusing to do the final step of storing a new overall inventory
386
* heuristic detection of renames between add and delete (out of scope for
389
* pushing changes to a master branch if any
391
* running hooks, pre and post commit
393
* prompting for a commit message if necessary, including a list of the
394
changes that have already been observed
396
* if there are tree references and recursing into them is enabled, then
399
Commit needs to protect against duplicated file ids
322
* when automatically adding new files or deleting missing files during
323
commit, they must be noted during commit and written into the working
326
* refuse "pointless" commits with no file changes - should be easy by
327
just refusing to do the final step of storing a new overall inventory
330
* heuristic detection of renames between add and delete (out of scope for
333
* pushing changes to a master branch if any
335
* running hooks, pre and post commit
337
* prompting for a commit message if necessary, including a list of the
338
changes that have already been observed
340
* if there are tree references and recursing into them is enabled, then
402
343
Updates that need to be made in the working tree, either on conclusion
403
344
of commit or during the scan, include
405
* Changes made to the tree shape, including automatic adds, renames or
408
* For trees (eg dirstate) that cache parent inventories, the old parent
409
information must be removed and the new one inserted
411
* The tree hashcache information should be updated to reflect the stat
412
value at which the file was the same as the committed version, and the
413
content hash it was observed to have. This needs to be done carefully to
414
prevent inconsistencies if the file is modified during or shortly after
415
the commit. Perhaps it would work to read the mtime of the file before we
416
read its text to commit.
346
* Changes made to the tree shape, including automatic adds, renames or
349
* For trees (eg dirstate) that cache parent inventories, the old parent
350
information must be removed and the new one inserted
352
* The tree hashcache information should be updated to reflect the stat
353
value at which the file was the same as the committed version, and the
354
content hash it was observed to have. This needs to be done carefully to
355
prevent inconsistencies if the file is modified during or shortly after
356
the commit. Perhaps it would work to read the mtime of the file before we
357
read its text to commit.
424
365
WorkingTree afterwards.
426
367
The command interface passes:
428
* a commit message (from an option, if any),
429
* or an indication that it should be read interactively from the ui object;
430
* a list of files to commit
431
* an option for a dry-run commit
432
* verbose option, or callback to indicate
433
* timestamp, timezone, committer, chosen revision id
435
* option for local-only commit on a bound branch
436
* option for strict commits (fail if there are unknown or missing files)
437
* option to allow "pointless" commits (with no tree changes)
369
* a commit message (from an option, if any),
370
* or an indication that it should be read interactively from the ui object;
371
* a list of files to commit
372
* an option for a dry-run commit
373
* verbose option, or callback to indicate
374
* timestamp, timezone, committer, chosen revision id
376
* option for local-only commit on a bound branch
377
* option for strict commits (fail if there are unknown or missing files)
378
* option to allow "pointless" commits (with no tree changes)
439
380
(This is rather a lot of options to pass individually and just for code tidyness maybe some of them should be combine into objects.)
441
382
>>> Branch.commit(from_tree, message, files_to_commit, ...)
492
433
The interface should not return a block for directories that are
493
434
recursively unchanged.
495
The tree's idea of what is possibly changed may be more conservative than
496
that of the branch. For example the tree may report on merges of files
497
where the text is identical to the parents: this must be recorded for
498
Bazaar branches that record per-file ancestry but is not necessary for all
499
branches. If the tree is responsible for determining when directories
500
have been recursively modified then it will report on all the parents of
501
such files. There are several implementation options:
503
1. Return all files and directories the branch might want to commit, even
504
if the branch ends up taking no action on them.
506
2. When starting the iteration, the branch can specify what type of change
507
is considered interesting.
509
Since these types of changes are probably (??) rare compared to files that
510
are either completely unmodified or substantially modified, the first may
511
be the best and simplest option.
513
The branch needs to build an inventory to commit, which must include
514
unchanged files within changed directories. This should be returned from
515
the working tree too. Repositories that store per-directory inventories
516
will want to build and store these from the lowest directories up.
517
For 0.17 format repositories with an all-in-one inventory it may be
518
easiest to accumulate inventory entries in arbitrary order into an
519
in-memory Inventory and then serialize it.
521
It ought to be possible to commit any Tree into a Branch, without
522
requiring a WorkingTree; the commit code should cope if the tree is not
523
interested in updating hashcache information or does not have a
527
Information from the tree to repository
528
---------------------------------------
530
The main things the tree needs to tell the Branch about are:
532
* A file is modified from its parent revision (in text, permissions,
533
other), and so its text may need to be stored.
535
Files should also be reported if they have more than one unique parent
536
revision, for repositories that store per-file graphs or last-change
537
revisions. Perhaps this behaviour should be optional.
539
**XXX:** are renames/deletions reported here too?
541
* The complete contents of a modified directory, so that its inventory
542
text may be stored. This should be done after all the contained files
543
and directories have been reported. If there are unmodified files,
544
or unselected files carried through from
546
XXX: Actually perhaps not grouped by directory, but rather grouped
547
appropriately for the shape of inventory storage in the repository.
549
In a zoomed-in checkout the workingtree may not have all the shape data
552
* A file is missing -- could cause either automatic removal or an aborted
555
* Any unknown files -- can cause automatic addition, abortion of a strict
556
commit, or just reporting.
559
Information from the repository to the tree
560
-------------------------------------------
562
After the commit the tree needs to be updated to the new revision. Some
563
information which was accumulated during the commit must be made available
564
to the workingtree. It's probably reasonable to hold it all in memory and
565
allow the workingtree to get it in whatever order it wants.
567
* A list of modified entries, and for each one:
569
* The stat values observed when the file was first read.
571
* The hash of the committed file text.
573
* The file's last-change revision, if appropriate.
575
This should include any entries automatically added or removed.
577
This might be construed as an enhanced version of ``set_parent_trees``.
578
We can avoid a stat on each file by using the value that was observed when
586
For a partial commit the directory contents may need to contain a mix of
587
entries from the working tree and parent trees. This code probably
588
shouldn't live in a specific tree implementation; maybe there should be a
589
general filter that selects paths from one tree into another?
591
However, the tree walking code does probably need to know about selected
592
paths to avoid examining unselected files or directories.
594
We never refuse selective file commits (except of merges).
601
What is common to all commit implementations, regardless of workingtree or
604
* Prompting for a commit message?
605
* Strictness/conflict checks?
608
How should this be separated?
615
For current and contemplated Bazaar storage formats, we can only finally
616
commit a directory after its contained files and directories have been
619
The dirstate workingtree format naturally iterates by directory in order
620
by path, yielding directories before their contents. This may also be the
621
most efficient order in which to stat and read the files.
623
One option would be to construe the interface as a visitor which reports
624
when files are detected to be changed, and also when directories are
436
The tree's idea of what is possibly changed may be more conservative than that of the branch. For example the tree may report on merges of files where the text is identical to the parents: this must be recorded for Bazaar branches that record per-file ancestry but is not necessary for all branches.
437
If the tree is responsible for determining when directories have been recursively modified then it will report on all the parents of such files.
438
There are several implementation options:
440
1. Return all files and directories the branch might want to commit, even if the branch ends up taking no action on them.
441
2. When starting the iteration, the branch can specify what type of change is considered interesting.
443
Since these types of changes are probably (??) rare compared to files that are either completely unmodified or substantially modified, the first may be the best and simplest option.
628
446
Open question: per-file graphs
added
removed
doc/developers/commit.txt
