  [[title
                /5.6/ Merging in Changes from Upstream
  ]]

 <"*(prev)*" -- $/hacking/commit.html> <"*(next)*" -- $/hacking/branch-publishing.html>


  While you work on a project in your local branch, the upstream
  branch of the same project may change.   *Merge* operations are
  used to add upstream's changes to your project trees.  There are
  many merge commands of which `star-merge' is often recommended:

  Consider the project tree from earlier sections:

  [[tty
    % tla tree-version
    lord@gnu.org--my-hacks-2005/tla--MYHACK--1.3.1

    % tla logs -s -r
    patch-1
        touch up COPYING and the top level Makefile.in
    base-0
        tag of lord@emf.net--2005/tla--fix-1--1.3.1--patch-1
  ]]

  The `logs' command can also tell you what changes you already 
  have from upstream:

  [[tty
    % tla logs -s -r lord@emf.net--2005/tla--fix-1--1.3.1
    patch-1
        fix 'pristines' regression
    base-0
        tag of lord@emf.net--2005/tla--devo--1.3.1--patch-21
  ]]

  The `revisions' command reports what changes upstream contains:

  [[tty
    % tla revisions -s -r lord@emf.net--2005/tla--fix-1--1.3.1
    patch-2
        add `NEW-FILE' for a docs-tla example
    patch-1
        fix 'pristines' regression
    base-0
        tag of lord@emf.net--2005/tla--devo--1.3.1--patch-21
  ]]

  The `missing' command reports what upstream changes are not 
  yet present in this tree.   You explicitly tell `missing'
  what you mean by "upstream":

  [[tty
    % tla missing -s -r lord@gnu.org--2005/tla--fix-1--1.3.1
    patch-2
        add `NEW-FILE' for a docs-tla example
  ]]


* Doing the Merge from Upstream

  [[tty
    % tla star-merge --three-way lord@gnu.org--2005/tla--fix-1--1.3.1
  ]]

  Note, after merging, the list of locally included changes from
  upstream has expanded and the list of changes missing has 
  shrunk (to nothing):

  [[tty
    % tla logs -s -r lord@emf.net--2005/tla--fix-1--1.3.1
    patch-2
        add `NEW-FILE' for a docs-tla example
    patch-1
        fix 'pristines' regression
    base-0
        tag of lord@emf.net--2005/tla--devo--1.3.1--patch-21


    % tla missing -s -r lord@gnu.org--2005/tla--fix-1--1.3.1
  ]]

  Examining the results will show that the merge added a new
  file to the tree (called `NEW-FILE').

  [[cartouche
                        `   /Merging is Local/

    Merging changes the checked-out project tree but it does not
    modify any archive.    After the merge in the example above,
    the command:

    [[tty
      % tla changes
    ]]

    will report the results of the merge as uncommited changes.

    To store the results of a merge in an archive you must, of course,
    use the <"`commit'" -- ./commit.html> command.
  ]]


* Commands Discussed

  [[tty
    % tla logs -H
    % tla revisions -H
    % tla missing -H
    % tla star-merge -H
    % tla changes -H
    % tla commit -H
  ]]


 <"*(prev)*" -- $/hacking/commit.html> <"*(next)*" -- $/hacking/branch-publishing.html>

* Copyright

  Copyright /(C)/ 2005 Tom Lord (`lord@emf.net')

  This program is free software; you can redistribute it and/or modify
  it under the terms of the /GNU General Public License/ as published by
  the Free Software Foundation; either version 2, or (at your option)
  any later version.

  This program is distributed in the hope that it will be useful,
  but \\/WITHOUT ANY WARRANTY/\\; without even the implied warranty of
  \\/MERCHANTABILITY/\\ or \\/FITNESS FOR A PARTICULAR PURPOSE/\\.  See the
  /GNU General Public License/ for more details.

  You should have received a copy of the /GNU General Public License/
  along with this software; see the file <"`COPYING'" --
  $/COPYING.html>.  If not, write to the Free Software Foundation, 675
  Mass Ave, Cambridge, MA 02139, USA.

 <"*(prev)*" -- $/hacking/commit.html> <"*(next)*" -- $/hacking/branch-publishing.html>

 [[null
   ; arch-tag: Tom Lord Wed Mar 30 14:05:05 2005 (merge-from-upstream.txt)
 ]]
