<div id="Binary-files"></div>
<div class="header">
<p>
Next: [[cvs: Multiple developers#Multiple developers|Multiple developers]], Previous: [[cvs: History browsing#History browsing|History browsing]], Up: [[cvs#Top|Top]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
<div id="Handling-binary-files"></div>
== Handling binary files ==
<div id="index-Binary-files"></div>

The most common use for <small>CVS</small> is to store text
files.  With text files, <small>CVS</small> can merge revisions,
display the differences between revisions in a
human-visible fashion, and other such operations.
However, if you are willing to give up a few of these
abilities, <small>CVS</small> can store binary files.  For
example, one might store a web site in <small>CVS</small>
including both text files and binary images.

<div class="menu-preformatted" style="font-family: serif">
 [[#The issues with binary files|&bull; Binary why]]::     More details on issues with binary files
 [[#How to store binary files|&bull; Binary howto]]::   How to store them
</div>


----

<div id="Binary-why"></div>
<div class="header">
<p>
Next: [[#How to store binary files|Binary howto]], Up: [[#Handling binary files|Binary files]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
<div id="The-issues-with-binary-files"></div>
=== The issues with binary files ===

While the need to manage binary files may seem obvious
if the files that you customarily work with are binary,
putting them into version control does present some
additional issues.

One basic function of version control is to show the
differences between two revisions.  For example, if
someone else checked in a new version of a file, you
may wish to look at what they changed and determine
whether their changes are good.  For text files,
<small>CVS</small> provides this functionality via the <code>cvs
diff</code> command.  For binary files, it may be possible to
extract the two revisions and then compare them with a
tool external to <small>CVS</small> (for example, word processing
software often has such a feature).  If there is no
such tool, one must track changes via other mechanisms,
such as urging people to write good log messages, and
hoping that the changes they actually made were the
changes that they intended to make.

Another ability of a version control system is the
ability to merge two revisions.  For <small>CVS</small> this
happens in two contexts.  The first is when users make
changes in separate working directories
(see [[cvs: Multiple developers#Multiple developers|Multiple developers]]).  The second is when one
merges explicitly with the &lsquo;<code>update -j</code>&rsquo; command
(see [[cvs: Branching and merging#Branching and merging|Branching and merging]]).

In the case of text
files, <small>CVS</small> can merge changes made independently,
and signal a conflict if the changes conflict.  With
binary files, the best that <small>CVS</small> can do is present
the two different copies of the file, and leave it to
the user to resolve the conflict.  The user may choose
one copy or the other, or may run an external merge
tool which knows about that particular file format, if
one exists.
Note that having the user merge relies primarily on the
user to not accidentally omit some changes, and thus is
potentially error prone.

If this process is thought to be undesirable, the best
choice may be to avoid merging.  To avoid the merges
that result from separate working directories, see the
discussion of reserved checkouts (file locking) in
[[cvs: Multiple developers#Multiple developers|Multiple developers]].  To avoid the merges
resulting from branches, restrict use of branches.


----

<div id="Binary-howto"></div>
<div class="header">
<p>
Previous: [[#The issues with binary files|Binary why]], Up: [[#Handling binary files|Binary files]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
<div id="How-to-store-binary-files"></div>
=== How to store binary files ===

There are two issues with using <small>CVS</small> to store
binary files.  The first is that <small>CVS</small> by default
converts line endings between the canonical form in
which they are stored in the repository (linefeed
only), and the form appropriate to the operating system
in use on the client (for example, carriage return
followed by line feed for Windows NT).

The second is that a binary file might happen to
contain data which looks like a keyword (see [[cvs: Keyword substitution#Keyword substitution|Keyword substitution]]), so keyword expansion must be turned
off.


The &lsquo;<code>-kb</code>&rsquo; option available with some <small>CVS</small>
commands insures that neither line ending conversion
nor keyword expansion will be done.

Here is an example of how you can create a new file
using the &lsquo;<code>-kb</code>&rsquo; flag:

<div class="example" style="margin-left: 3.2em">
 $ echo '$<i></i>Id$' &gt; kotest
 $ cvs add -kb -m&quot;A test file&quot; kotest
 $ cvs ci -m&quot;First checkin; contains a keyword&quot; kotest
</div>

If a file accidentally gets added without &lsquo;<code>-kb</code>&rsquo;,
one can use the <code>cvs admin</code> command to recover.
For example:

<div class="example" style="margin-left: 3.2em">
 $ echo '$<i></i>Id$' &gt; kotest
 $ cvs add -m&quot;A test file&quot; kotest
 $ cvs ci -m&quot;First checkin; contains a keyword&quot; kotest
 $ cvs admin -kb kotest
 $ cvs update -A kotest
 # <span class="roman" style="font-family:serif; font-weight:normal">For non-unix systems:</span>
 # <span class="roman" style="font-family:serif; font-weight:normal">Copy in a good copy of the file from outside CVS</span>
 $ cvs commit -m &quot;make it binary&quot; kotest
</div>

When you check in the file &lsquo;<tt>kotest</tt>&rsquo; the file is
not preserved as a binary file, because you did not
check it in as a binary file.  The <code>cvs
admin -kb</code> command sets the default keyword
substitution method for this file, but it does not
alter the working copy of the file that you have.  If you need to
cope with line endings (that is, you are using
<small>CVS</small> on a non-unix system), then you need to
check in a new copy of the file, as shown by the
<code>cvs commit</code> command above.
On unix, the <code>cvs update -A</code> command suffices.
(Note that you can use <code>cvs log</code> to determine the default keyword
substitution method for a file and <code>cvs status</code> to determine
the keyword substitution method for a working copy.)

However, in using <code>cvs admin -k</code> to change the
keyword expansion, be aware that the keyword expansion
mode is not version controlled.  This means that, for
example, that if you have a text file in old releases,
and a binary file with the same name in new releases,
<small>CVS</small> provides no way to check out the file in text
or binary mode depending on what version you are
checking out.  There is no good workaround for this
problem.

You can also set a default for whether <code>cvs add</code>
and <code>cvs import</code> treat a file as binary based on
its name; for example you could say that files who
names end in &lsquo;<code>.exe</code>&rsquo; are binary.  See [[cvs: Reference manual for Administrative files#The cvswrappers file|Wrappers]].
There is currently no way to have <small>CVS</small> detect
whether a file is binary based on its contents.  The
main difficulty with designing such a feature is that
it is not clear how to distinguish between binary and
non-binary files, and the rules to apply would vary
considerably with the operating system.


----

<div class="header">
<p>
Previous: [[#The issues with binary files|Binary why]], Up: [[#Handling binary files|Binary files]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
This document was generated on <i>a sunny day</i> using [http://www.nongnu.org/texi2html/ <i>texi2html</i>].
