Other information¶
This chapter is being rewriten, and its parts moved around/elsewhere. Some of it may be inaccurate. Please be patient.
The weld XML file¶
A simple weld XML file:
<?xml version="1.0" ?>
<weld name="frank">
<origin uri="ssh://git@home.example.com/ribbit/fromble" />
<base name="project124" uri="ssh://git@foo.example.com/my/base" branch="b" rev=".." tag=".."/>
<base name="igniting_duck" uri="ssh://git@bar.example.com/wobble" />
<seam base="project124" dest="flibble" />
<seam base="igniting_duck" source="foo" dest="bar" />
</weld>
This file tells weld:
- This weld is called frank. This name is not used for anything at the moment (caveat: It is put into the “X-Weld-State: Pushed” markers in the base, but otherwise never referenced).
- The origin for this weld is at ssh://git@home.example.com/ribbit/fromble.
- This weld draws from two bases: project124 and igniting_duck.
- project124 turns up in a directory in the weld called flibble.
- igniting_duck/foo turns up in <weld>/bar
Details¶
The XML file must:
- start with an XML version line:
<?xml version="1.0" ?>
, because otherwise it wouldn’t be XML - continue with the start of a weld definition:
<weld name=
name>
. Whilst the weld name is required, it is not currently used for anything. - which contains an
<origin uri=
origin/>
entity (althogh theuri
is optional at the moment) - as well as zero or more base and seam definitions
- and end with the end of a weld definition:
</weld>
Comments are allowed as normal, and are ignored (and will not be retained when the XML file is copied).
Only one weld definition is allowed in a file, although this may or may not be checked - regardless, any weld definitions after the first are ignored.
With a weld definition, there are two types of entity:
- base definitions
- seam definitions
A base definition must occur before the seam definitions that belong to it, but otherwise the order of entries is not important. A seam may only belong to a single base. A base without any seams is not forbidden by the file syntax, but will not be of much use.
A base definition contains:
name
- the name of this baseuri
- the URI for the repository from which this base is to cloned/checked outbranch
,rev
ortag
- the branch, revision or tag to clone/check out. These defaut to “master”, “HEAD” and (essentially) “HEAD” respectively. It is not currently defined what happens if you specify more than one of these for a particular base.
A seam definition contains:
base
- the name of the base that this seam belongs to. This base must already have been defined in the XML file.name
- the name of this seam. This is optional, and defaults to Nonesource
- the directory in the bare repository from which the seam’s contents are taken. This is optional, and defaults to"."
, meaning the top (root) of the repository. Thesource
may specify a sub-directory, e.g., “src/base/libuseful”.dest
- the directory in the weld to which the seam’s contents should be copied. This is optional and defaults to"."
, meaning the top (root) of the weld. Thedest
may specify a sub-directory, e.g., “kynesim/main/useful”.current
- This is optional and is not used at the moment - it may be withdrawn in future versions of weld.
It is not defined what happens if the same base or seam is defined more than once (with either the same values or different values). Future versions of weld may reject an XML file that does this.
It is intended that two bases with diffferent names be regarded as different, although what happens if that is the only difference between them is not defined.
Warning
Do not cross the streams.
Specifically, no two different seams should have the same destination, lest
weld get terribly confused.
"."
counts, so you cannot have more than one seam with no dest
.
This also means that destinations that “nest” (e.g., src/fred
and
src/fred/jim
) are forbidden.
Note
I am not aware of anything that ensures that the origin URI corresponds to the place that you actually clone the weld from. Indeed, since it is a URI (and not a URL), it need not so correspond. However, if you do something obscure based on this, then no-one is going to like you.
Files in .weld¶
When you first clone a weld, the only file in the .weld
directory will be:
welded.xml
- this is the file that describes this weld. It is a copy of the XML file given to weld init.
After doing a weld pull
, a weld push
, or a weld query
on a base
(which may need to “pull” the base to find out about it), there will also be:
bases/
- this is a directory containing a clone of each of your bases, retrieved as they are needed.
You may also see:
counter
- this is a file whose content counts upward. It is used to force changes so we never have empty commits when doingweld pull
(orweld push
). It appears to be necessary because -git commit --allow-empty
can sometimes lose commits.
During a weld pull
or weld push
you will also see:
complete.py
- the script thatweld finish
runs.abort.py
- the script thatweld abort
runs.
and weld push
also creates:
pushing/
- which contains the commit message to be used at the end of theweld push
, and a marker to indicate whether a merge is in progress.
All of these should be deleted when the weld pull
or weld push
is
finished (and, specifically, weld finish
and weld abort
should delete
them).
A summary of weld commands¶
weld init <weld-xml-file>
This command takes a <weld-xml-file> that you have written and creates a git repository for it.
The XML file is written to
.weld/welded.xml
.An initial
.gitignore
file is created, which tells git to ignore various weld working files, including.weld/bases
.
weld pull <base-name>
The special “name”_all
means “pull all bases”.
weld finish
Finish a weld pull or push that had problems (indicating that the problems were fixed).
weld abort
Abort a weld pull or push that had problems (thus discarding it)
weld query bases
List the bases, and their seams
weld query base <base-name>
Report on the current state of the named base.
weld query seam-changes <base-name>
Report on the seam changes for the named base.
weld status
If we are part way through a
weld pull
orweld push
say so.Otherwise, report on whether we should do a
git pull
orgit push
of our weld. This is intended to be useful before doing aweld pull
orweld push
of our bases.
Commit messages that weld inserts¶
Weld will occasionally leave commits containing messages to itself.
It is important that you do not start any other commit messages
with X-Weld-State
The messages it leaves are:
X-Weld-State: Init
Indicates that the weld started here (with nothing merged)
X-Weld-State: PortedCommit <base-name>/<commit-id> [<seams>]
Indicates that it ...
X-Weld-State: Seam-Added <base-name>/<commit-id> [<seams>]
Indicates that it ...
X-Weld-State: Seam-Deleted <base-name>/<commit-id> [<seams>]
Indicates that it ...
X-Weld-State: Seam-Changed <base-name>/<commit-id> [<seams>]
Indicates that it ...
X-Weld-State: Merged <base-name>/<commit-id> [<seams>]
Indicates that it merged <base-name> <commit-id> with the following seams.
X-Weld-State: Pushed <base-name>/<commit-id> [<seams>]
Indicates that it ...
Note that the X-Weld-State: Seam-
messages only occur in the branches on
which base merging is done.
In the base repositories, it can also leave a commit message of the form:
X-Weld-State: Pushed <base-name> from weld <weld-name>
This commit will then contain a sequence of lines, each of which is (currently) the “short” SHA1 id for a squashed component commit, followed by its one line summary - so for instance:
X-Weld-State: Pushed igniting_duck from weld fromble
e8addb1 Add trailing comments across the bases and to the weld
7eaa68a One-duck: Also build one-duck, same as one
f589384 One-duck: Add a comment to the end of the Makefile
The format of this message may change in the future.