bk pull(7.3ce)              BitKeeper User's Manual             bk pull(7.3ce)

NAME
       bk pull - update a repository from its parent[s]

SYNOPSIS
       bk pull [-iqRsTuv] [-c<n>] [-r<rev>] [<parent> ...]

DESCRIPTION
       bk  pull updates a repository from its incoming parent[s].  Changes are
       retrieved and automatically applied, if possible.   You  will  only  be
       asked  to  resolve  conflicts by hand if a file has overlapping changes
       (changes where both repositories have touched the same line in the same
       file).

       To see what would be pulled run

           bk changes -aR

       bk  pull  normally  runs  resolve,  the  tool  which applies the pulled
       changes, automatically.  Resolve will look at each  change,  make  sure
       there  are no conflicts that it can't merge, and apply the change.  You
       may have to (or want to) run resolve manually.   If  you  do  not  want
       automatic  merges,  i.e.,  you  want to diff them by hand, then use the
       "-i" option.  If resolve was run automatically and it found  conflicts,
       the  changes have not been applied; you will need to run an interactive
       resolve to merge and apply the changes.

       You can override the default parent  by  specifying  a  different  one.
       Doing so changes the parent for the duration of this command only.

       If  you've  pulled in error you may use bk unpull to remove the change-
       sets introduced by the pull.  Please read the bk unpull  man  page  for
       important information about what is and is not unpulled.

SAFETY
       In non-nested BitKeeper, after you have pulled from a given repository,
       it is safe to delete the sending side as all the changes  it  contained
       have been transferred. This is not necessarily true in a nested collec-
       tion since the set of components populated in the sending side and  the
       set  of  components  populated  in  the receiving side might not be the
       same.

       In order to solve this problem, BitKeeper  utilizes  gates,  which  are
       repositories  that  you set up as permanent (e.g. integration reposito-
       ries or masters). The URLs for the gates are  remembered  by  BitKeeper
       and used when pulling from non-gate repositories.

       When  pulling from a nested repository, if the sending side of the pull
       is not a gate, BitKeeper will default to 'safe' mode. In safe mode, all
       components  populated  in  the sending side that are not found in gates
       are transferred to the receiving side.  This  preserves  the  attribute
       that  pulling  from  a repository transfers all unique information thus
       allowing the sending side of the pull to be deleted.

       When pulling from a gate, BitKeeper defaults to unsafe  mode.  In  this
       mode,  only the components that are populated in the receiving side are
       included in the pull. ChangeSets made to components in the sending side
       (the  gate)  that  are  not populated in the receiving side will not be
       transferred. In this case, removing the sending side (the  gate)  could
       result  in lost work. Only mark as gates repositories that you know are
       not going to be deleted.

       When pulling in safe mode, BitKeeper will try hard  not  to  break  the
       aliases  in  the  sending  side  while  at the same time minimizing the
       amount of information that needs to be  transferred  to  the  receiving
       side.  This  means that if the sending side has many aliases populated,
       and only some of those would be sufficient to account for all the  com-
       ponents with unique work, only those aliases would be transferred.

       An  example:  suppose the sending side has components A and B, with new
       work in both.  Suppose the receiving repository just  has  A.   Pulling
       from  the sending side is considered "unsafe" when only the A csets are
       sent but "safe" when the A csets and B component are sent.

OPTIONS
       --auto-populate automatically populate missing components as needed  to
                       perform a "safe" pull.

       --auto-port automatically  turn  the pull into a port if needed.
                   Only works in standalone repositories.  Useful  when
                   multiple parents are a combination of standalone and
                   components.
       --batch     Pass "--batch" to resolve ("--batch" means do not do
                   interactive resolve of any conflicts, leave that for
                   later.)  Mutually exclusive with "-i".
       -c<n>       try to get the remote lock <n> times  before  giving
                   up (default forever).
       -E<env>=<val>
                   Export  environment  variable  to  remote site.  The
                   environment variable must start with BKU_.
       -i          Turn off automerge feature  in  resolve.   For  each
                   file with parallel work, you are prompted to examine
                   the changes and  either  manually  or  automatically
                   merge them.  Mutually exclusive with "--batch".
       -q          Be quiet.
       -R          Do  not run resolve at all.  You must run bk resolve
                   later.
       -r<rev>     Pull up to and including this revision, but  exclude
                   later  changes.   (Or key or changeset revision. See
       --safe      In a nested collection, using this option means that
                   the  source repository may be safely removed after a
                   successful pull.  Either  the  destination  received
                   everything  that  the  source had, or the non-pulled
                   components were found in a safe location  (a  gate).
                   This  option  is  implied when pulling from a nested
                   collection that is not a gate.  This option  has  no
                   effect  in a traditional standalone repository.  See
                   also --unsafe below.
       --stats     After finishing the  pull,  print  statistics  about
                   what  was  pulled. The format is compatible with the
                   output of bk diff --stats-only.  This option can  be
                   permanently turned on with the stats_after_pull con-
                   figuration variable. See bk  help  config  for  more
                   information.
       -T          Pass  "-T" to resolve ("-T" means do not use the GUI
                   tools.)
       -u          Do not complete the pull if there are local  change-
                   sets,  i.e., insist that this operation is an update
                   operation.
       --unsafe    In a nested collection, using this option means that
                   the  source  repository may contain work that is not
                   pulled into the destination.   --unsafe  means  pull
                   updates  only to the components and/or aliases popu-
                   lated in the destination.  This option has no effect
                   in a traditional standalone repository.  This option
                   is implied when  pulling  from  a  gate.   See  also
                   --safe above.
       -v          Be verbose by listing each file.

SEE ALSO
       bk bkd
       bk changes
       bk gate
       bk parent
       bk push
       bk resolve
       bk triggers
       bk unpull

CATEGORY
       Common
       Repository

BitKeeper Inc                         1E1                       bk pull(7.3ce)