view mercurial/help/phases.txt @ 24735:07200e3332a1

tags: extract .hgtags filenodes cache to a standalone file

Resolution of .hgtags filenodes values has historically been a
performance pain point for large repositories, where reading individual
manifests can take over 100ms. Multiplied by hundreds or even thousands
of heads and resolving .hgtags filenodes becomes a performance issue.

This patch establishes a standalone cache file holding the .hgtags
filenodes for each changeset. After this patch, the .hgtags filenode
for any particular changeset should only have to be computed once
during the lifetime of the repository.

The introduced hgtagsfnodes1 cache file is modeled after the rev branch
cache: the cache is effectively an array of entries consisting of a
changeset fragment and the filenode for a revision. The file grows in
proportion to the length of the repository (24 bytes per changeset) and
is truncated when the repository is stripped. The file is not written
unless tag info is requested and tags have changed since last time.

This patch partially addresses issue4550. Future patches will split the
"tags" cache file into per-filter files and will refactor the cache
format to not capture the .hgtags fnodes, as these are now stored in
the hgtagsfnodes1 cache. This patch is capable of standing alone. We
should not have to wait on the tags cache filter split and format
refactor for this patch to land.

What are phases?
================

Phases are a system for tracking which changesets have been or should
be shared. This helps prevent common mistakes when modifying history
(for instance, with the mq or rebase extensions).

Each changeset in a repository is in one of the following phases:

 - public : changeset is visible on a public server
 - draft : changeset is not yet published
 - secret : changeset should not be pushed, pulled, or cloned

These phases are ordered (public < draft < secret) and no changeset
can be in a lower phase than its ancestors. For instance, if a
changeset is public, all its ancestors are also public. Lastly,
changeset phases should only be changed towards the public phase.

How are phases managed?
=======================

For the most part, phases should work transparently. By default, a
changeset is created in the draft phase and is moved into the public
phase when it is pushed to another repository.

Once changesets become public, extensions like mq and rebase will
refuse to operate on them to prevent creating duplicate changesets.
Phases can also be manually manipulated with the :hg:`phase` command
if needed. See :hg:`help -v phase` for examples.

Phases and servers
==================

Normally, all servers are ``publishing`` by default. This means::

 - all draft changesets that are pulled or cloned appear in phase
 public on the client

 - all draft changesets that are pushed appear as public on both
 client and server

 - secret changesets are neither pushed, pulled, or cloned

.. note::

  Pulling a draft changeset from a publishing server does not mark it
  as public on the server side due to the read-only nature of pull.

Sometimes it may be desirable to push and pull changesets in the draft
phase to share unfinished work. This can be done by setting a
repository to disable publishing in its configuration file::

  [phases]
  publish = False

See :hg:`help config` for more information on configuration files.

.. note::

  Servers running older versions of Mercurial are treated as
  publishing.

.. note::

   Changesets in secret phase are not exchanged with the server. This
   applies to their content: file names, file contents, and changeset
   metadata. For technical reasons, the identifier (e.g. d825e4025e39)
   of the secret changeset may be communicated to the server.


Examples
========

 - list changesets in draft or secret phase::

     hg log -r "not public()"

 - change all secret changesets to draft::

     hg phase --draft "secret()"

 - forcibly move the current changeset and descendants from public to draft::

     hg phase --force --draft .

 - show a list of changeset revision and phase::

     hg log --template "{rev} {phase}\n"

 - resynchronize draft changesets relative to a remote repository::

     hg phase -fd "outgoing(URL)"

See :hg:`help phase` for more information on manually manipulating phases.