diff options
author | Tammy Fox <tfox@redhat.com> | 2003-09-22 16:28:26 +0000 |
---|---|---|
committer | Tammy Fox <tfox@redhat.com> | 2003-09-22 16:28:26 +0000 |
commit | 8b1d9abdd1384cb7ea831f4321ce8f6638337d82 (patch) | |
tree | d64fbe55464d817f26a6e4aa3abe4ccd1164f383 /common/cvs-en.xml | |
parent | 5ace6fc786e85f49b2352fcb221fb480a84dbc64 (diff) | |
download | fedora-doc-utils-8b1d9abdd1384cb7ea831f4321ce8f6638337d82.tar.gz fedora-doc-utils-8b1d9abdd1384cb7ea831f4321ce8f6638337d82.tar.xz fedora-doc-utils-8b1d9abdd1384cb7ea831f4321ce8f6638337d82.zip |
add developer guide
Diffstat (limited to 'common/cvs-en.xml')
-rw-r--r-- | common/cvs-en.xml | 807 |
1 files changed, 807 insertions, 0 deletions
diff --git a/common/cvs-en.xml b/common/cvs-en.xml new file mode 100644 index 0000000..f13413b --- /dev/null +++ b/common/cvs-en.xml @@ -0,0 +1,807 @@ + <chapter id="ch-cvs"> + <title>CVS</title> + + <para> + CVS, or Concurrent Versions System, provides a framework for multiple + users to edit the same files. As you can imagine, if a group of users + edits the files in a single directory, chaos would reign. Using CVS, + however, a group of people can safely work on the same set of files. CVS + keeps the master copy of the files, and it records who changed what and + when in a central repository. If conflicts arise, CVS lets you know. CVS + is usually used so that programmers can share code, but it also works well + for documentation. + </para> + + <indexterm> + <primary>cvs</primary> + </indexterm> + + <sect1 id="s1-cvs-overview"> + <title>How CVS Works</title> + + <indexterm> + <primary>cvs</primary> + <secondary>how it works</secondary> + </indexterm> + + <indexterm> + <primary>cvs</primary> + <secondary>overview</secondary> + </indexterm> + + <para> + In most cases, each set of files that make up a package or project is + stored as a <firstterm>module</firstterm> on the CVS server. + </para> + + <para> + When working with files from CVS, you <firstterm>checkout</firstterm> a + copy of the module on your local file system. After modifying one or + more files, you <firstterm>commit</firstterm> them back to the central + CVS repository server. + </para> + + <para> + When you commit changes, only changes to files the server knows about + are committed. In other words, if you created a file in your local + checkout of a module, the new file is not automatically uploaded to the + server. You must <firstterm>add</firstterm> the file to the repository + and then commit it. If you remove a file from your local checkout of a + module, you must specify that you want to remove it from the repository + on the CVS server and then commit the removal of the file. + </para> + + <para> + The specific commands to perform these actions are discussed in <xref + linkend="s1-cvs-cvscommands"></xref>. + </para> + + <para> + If someone has modified the file between the last time you grabbed the + file from CVS and when you try to commit a change, it tried to merge the + changes into the master copy of the CVS server. If the content you + changed is in a different location in the file than the content changed + by someone else, chances are, the commit action will go through without + a <firstterm>conflict</firstterm>. If someone modified the same content + as the content you just changed and tried to commit, you will see a + message that a file conflict has occurred. Thus, you need to + <firstterm>update</firstterm> your files frequently. It is a good + practice to update them right before you start modifying a file. Refer + to <xref linkend="s2-cvs-cvscommands-conflicts"></xref> for instructions + on resolving conflicts. + </para> + + </sect1> +<!-- + <sect1 id="s1-cvs-setup"> + <title>Setting Up CVS</title> + + <indexterm> + <primary>cvs</primary> + <secondary>setting up</secondary> + </indexterm> + + <para> + Before using CVS, you need a CVS account. This section provides + instructions necessary to setup an account. After getting an account, + you do not need to perform these actions again. + </para> + + + <sect2 id="s2-cvs-generate-keys"> + <title>Generating Keys</title> + <indexterm> + <primary>OpenSSH</primary> + <secondary>authorization keys</secondary> + </indexterm> + + <para> + The CVS server uses SSH Protocol 2 keys to authenticate users. Thus, you + need to generate a pair of keys before applying for a CVS account. + </para> + + <para> + Use the following steps to generate a DSA key used by SSH Protocol 2. + It is required for an <computeroutput>rhlinux.redhat.com</computeroutput> + CVS account. + </para> + <orderedlist> + <indexterm> + <primary>OpenSSH</primary> + <secondary><command>ssh-keygen</command></secondary> + </indexterm> + <indexterm> + <primary><command>ssh-keygen</command></primary> + </indexterm> + <listitem> + <para>To generate a DSA key to work with version 2.0 protocol, at a + shell prompt, type the command: + </para> +<screen> +<command>ssh-keygen -t dsa</command> +</screen> + <para>Accept the default file location of + <filename>~/.ssh/id_dsa</filename>. Enter a passphrase different + than your account password and confirm it by entering it again. + </para> + </listitem> + <listitem> + <para>Copy your new key to the correct file by typing the following at a + shell prompt (if <filename>~/.ssh/authorized_keys</filename> already + exists, the contents of <filename>~/.ssh/id_dsa.pub</filename> will be + appended to the end of the <filename>~/.ssh/authorized_keys</filename> + file): + </para> +<screen> +<command>cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys</command> +</screen> + </listitem> + <listitem> + <para>Change the permissions of your <filename>.ssh</filename> directory + and your keys with the commands + </para> +<screen> +<command>chmod 755 ~/.ssh</command> +<command>chmod 644 ~/.ssh/authorized_keys</command> +</screen> + </listitem> + </orderedlist> + + <tip> + <title>Tip</title> + <para> + You can have your system remember your passphrase so that you do not + have to type it every time you access the CVS server. If you are + running GNOME, skip to <xref linkend="s1-ssh-with-gnome"></xref>. If you are not + running the X Window System, skip to <xref linkend="s1-ssh-without-x"></xref>. + </para> + </tip> + </sect2> + + </sect1> +--> + + <sect1 id="s1-cvs-configure"> + <title>Configuring CVS on Your System</title> + + <indexterm> + <primary>cvs</primary> + <secondary>configuring your system for</secondary> + </indexterm> + + <para> + You need to have the RPM package <filename>cvs</filename> installed to + use CVS. + </para> + + <indexterm> + <primary>cvs</primary> + <secondary>CVSROOT</secondary> + </indexterm> + + <indexterm> + <primary>cvs</primary> + <secondary>CVS_RSH</secondary> + </indexterm> + + <indexterm> + <primary>CVSROOT</primary> + </indexterm> + + <indexterm> + <primary>CVS_RSH</primary> + </indexterm> + + <indexterm> + <primary>cvs</primary> + <secondary><filename>.cvsrc</filename></secondary> + </indexterm> + <indexterm> + <primary><filename>.cvsrc</filename></primary> + </indexterm> + + <para> + Follow these steps to configure your CVS environment: + </para> + <orderedlist> + <listitem> + <para>In your favorite Linux editor, add the following lines to your + <filename>~/.bashrc</filename> (replace + anonymous with your username if you have an account) + </para> +<screen> +<computeroutput>export CVSROOT=:ext:anonymous@rhlinux.redhat.com:/usr/local/CVS +export CVS_RSH="ssh"</computeroutput> +</screen> + </listitem> + <listitem> + <para>Use the command <command>source ~/.bashrc</command> to have the + changes take effect. + </para> + </listitem> + <listitem> + <para>Create a file named <filename>.cvsrc</filename> in your home + directory. It should contain the following: +<screen> +<computeroutput>cvs -z3 +diff -uN +rdiff -uN +update -dP</computeroutput> +</screen> + </para> + </listitem> + <listitem> + <para>Change directories to where you want your files from CVS to be + located. Use the command <command>cvs checkout + <replaceable><module-name></replaceable></command> to checkout + the desired modules. Refer to <xref + linkend="s1-cvs-cvscommands"></xref> if you need help using + CVS. + </para> + </listitem> + </orderedlist> + + <para> + Once you have checked it out, it doesn't matter what your + <envar>CVSROOT</envar> is set to because it is stored in the file + <filename>CVS/Root</filename> for each directory in your local + repository. + </para> + + </sect1> + + <sect1 id="s1-cvs-cvscommands"> + <title>Basic CVS Commands</title> + + <indexterm> + <primary>cvs</primary> + <secondary>commands</secondary> + </indexterm> + + <para> + After configuring your system to work with CVS, checkout the modules you + will be working on. + </para> + + <sect2 id="s2-cvs-cvscommands-co"> + <title>Checking Out Modules</title> + + <indexterm> + <primary>cvs</primary> + <secondary>checking out modules</secondary> + </indexterm> + + <para> + You only need to checkout a module once. After a local copy of the + module is on your system, it is on your system. + </para> + + <para> + To checkout a module, use the following command: + </para> + +<screen> +<command>cvs co <replaceable><module-name></replaceable></command> +</screen> + + <para> + For example, to checkout the + <computeroutput>redhat-logviewer</computeroutput> module, change to + your work directory, and execute the following command: + </para> + +<screen> +<command>cvs co redhat-logviewer</command> +</screen> + + <para> + A directory called <filename>redhat-logviewer/</filename> is created + in the current directory. + </para> + + <para> + If a branch name is not specified when checking out a module, it is + referred to as the <firstterm>HEAD</firstterm> of the CVS module. + </para> + + <sect3 id="s3-cvs-cvscommands-co-branch"> + <title>Checking Out Branches of Modules</title> + + <indexterm> + <primary>cvs</primary> + <secondary>check out modules</secondary> + <tertiary>checking out branches</tertiary> + </indexterm> + + <para> + Think of a CVS branch as a version of the files for a particular + version of a manual or package. + </para> + + <para> + To checkout a branch of a module, use the following command: + </para> + +<screen> +<command>cvs co -d <replaceable><directory></replaceable> -r <replaceable><branchname></replaceable> <replaceable><module-name></replaceable></command> +</screen> + + <para> + A directory named <replaceable><directory></replaceable> is created, + and the files for the <replaceable><branchname></replaceable> branch + of the <replaceable><module-name></replaceable> module are copied in + the directory. + </para> + + <para> + For example, to checkout a branch named BRANCH-VERSION-1.2 from the + <computeroutput>mymodule</computeroutput> module, use the command: + </para> + +<screen> +<command>cvs co -d mymodule-1.2 -r BRANCH-VERSION-1.2 mymodule</command> +</screen> + + <para> + The BRANCH-VERSION-1.2 branch of the module is checked out in the + <filename>mymodule-1.2</filename> directory on your system. + </para> + + <para> + To determine which branches and tags exist for a file, use the command: + </para> +<screen> +<command>cvs status -v <replaceable><filename></replaceable></command> +</screen> + + <para> + For example, the status of the file <filename>foo.sgml</filename> is + as follows: + </para> +<screen> +<computeroutput> +=================================================================== +File: foo.sgml Status: Up-to-date + + Working revision: 1.47 + Repository revision: 1.47 /usr/local/CVS/docs/custom-guide/rhl-cg-en.sg +ml,v + Sticky Tag: (none) + Sticky Date: (none) + Sticky Options: (none) + + Existing Tags: + BRANCH-VERSION-1.2 (branch: 1.25.2) +</computeroutput> +</screen> + + <para> + Only tags marked as branches in the second column under the + <computeroutput>Existing Tags</computeroutput> section can be + checked out as a branch. + </para> + + </sect3> + + </sect2> + + <sect2 id="s2-cvs-cvscommands-up"> + <title>Updating Files</title> + + <indexterm> + <primary>cvs</primary> + <secondary>updating files</secondary> + </indexterm> + + <para> + To retrieve the latest versions of the files in a module, change to + the directory that contains the files for the module and execute the + command: + </para> +<screen> +<command>cvs up</command> +</screen> + + <para> + The latest versions of all the files in the module are downloaded into + your local copy. If you notice a file conflict, refer to <xref + linkend="s2-cvs-cvscommands-conflicts"></xref>. + </para> + + </sect2> + + <sect2 id="s2-cvs-cvscommands-commit"> + <title>Committing Files</title> + + <indexterm> + <primary>cvs</primary> + <secondary>committing files</secondary> + </indexterm> + + <para> + After modifying files in your local version of a module, commit them + to save the changes on the CVS server: + </para> +<screen> +<command>cvs commit -m "some log message" <filename><replaceable><filename></replaceable></filename></command> +</screen> + + <para> + The log message should be as descriptive as possible so that you and + anyone else working on the module understands what changed. Using a + log message such as <userinput>updated some files</userinput> does not + accurately describe what has changed and will not help you in the + future. + </para> + + <para> + <filename><replaceable><filename></replaceable></filename> can + be one filename, a series of filenames separated by spaces, or a group + of filenames specified using wildcards such as + <filename>*.png</filename> or <filename>foo-*.sgml</filename>. + </para> + + <para> + If no filename or group of filenames is specified in the commit + command, all files that have been changed in the module, added to the + module with the <command>cvs add</command> command, and removed with + the <command>cvs rm</command> command are committed to the server. All + files in the module means that the command is recursive. It is not + good practice to issue the commit command without a filename or group + of filenames specified because you might not remember exactly what + files changed. + </para> + + <para> + If you notice a file conflict, refer to <xref + linkend="s2-cvs-cvscommands-conflicts"></xref>. + </para> + + </sect2> + + + <sect2 id="s2-cvs-cvscommands-add"> + <title>Adding Files</title> + + <indexterm> + <primary>cvs</primary> + <secondary>adding files</secondary> + </indexterm> + + <para> + To add a file to a module, create the file in your local copy, and + execute the following command: + </para> +<screen> +<command>cvs add <filename><file-to-add></filename></command> +</screen> + + <para> + After adding the file, you must commit the add to copy it to the + server: + </para> + +<screen> +<command>cvs commit -m "some log message" <filename><file-to-add></filename></command> +</screen> + + </sect2> + + <sect2 id="s2-cvs-cvscommands-rm"> + <title>Removing Files</title> + + <indexterm> + <primary>cvs</primary> + <secondary>removing files</secondary> + </indexterm> + + <para> + If a file is no longer needed in the module, use the following command + to remove it from your local version and commit the removal to the + server. Even though the file is removed from current version of the + module, an archived copy is still kept on the server and can be + retrieved at any time. + </para> +<screen> +<command>cvs rm -f <filename><file-to-remove></filename></command> +</screen> + + <para> + After removing the file, you must commit the removal: + </para> + +<screen> +<command>cvs commit -m "some log message" <filename><file-to-remove></filename></command> +</screen> + + <para> + You can not use wildcards in the commit command to commit removed + files. They must be specified with the complete filenames. + </para> + + <para> + If you need to rename a file, it is best to rename the file on the CVS + server so that the history of the file is preserved. If you need to + rename a file, contact Tammy (or whoever is the technical lead). + </para> + + </sect2> + + <sect2 id="s2-cvs-cvscommands-status"> + <title>Status of Files</title> + + <indexterm> + <primary>cvs</primary> + <secondary>status of files</secondary> + </indexterm> + + <para> + Sometimes it is necessary to view the <firstterm>status</firstterm> of + a file in a CVS module. To view the status of a file, use the command: + </para> + +<screen> +<command>cvs status <filename><filename></filename></command> +</screen> + + <para> + The statuses of a file in the repository are as follows: + </para> + <variablelist> + <varlistentry> + <term><computeroutput>Up-to-date</computeroutput></term> + <listitem> + <para>Your revision of the file is identical to the latest + revision on the CVS server.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput>Locally Modified</computeroutput></term> + <listitem> + <para>You have update to the latest revision from the server, but + then you modified the file in your checkout.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput>Locally Added</computeroutput></term> + <listitem> + <para>You added the file with the <command>cvs add</command> + command but have not yet committed the addition of the + file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput>Locally Removed</computeroutput></term> + <listitem> + <para>You removed the file with the <command>cvs remove</command> + command but have not yet committed the removal.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput>Needs Checkout</computeroutput></term> + <listitem> + <para>A newer version of the file is on the server and needs to be + retrieved. Even though the status includes the word checkout, it + really means that you need to update your files with the + <command>cvs update</command> command.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput>Needs Patch</computeroutput></term> + <listitem> + <para>The revision in your local checkout needs a patch to be the + latest revision from the server. Issue the <command>cvs + update</command> command to resolve.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput>Needs Merge</computeroutput></term> + <listitem> + <para>A newer revision exists on the server and your local version + contains modification not yet committed. This status usually + occurs if you don't have the latest revision of the file and + edit it anyway.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput>File had conflicts on merge</computeroutput></term> + <listitem> + <para>Similar to <computeroutput>Needs Merge</computeroutput>, + except when you tried to issue the <command>cvs update</command> + command, the differences could not be resolved + automatically. Refer to <xref linkend="s2-cvs-cvscommands-conflicts"></xref> + for more information on resolving conflicts.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput>Unknown</computeroutput></term> + <listitem> + <para>The CVS server does not know anything about this file. It + has not been added or removed locally and has never been + committed to the server. This status usually occurs for files + you should not commit to CVS such as + <filename>generated-index.sgml</filename> or for files that you + want to add to the repository but have not issued the + <command>cvs add</command> command for yet.</para> + </listitem> + </varlistentry> + </variablelist> + + </sect2> + + <sect2 id="s2-cvs-cvscommands-conflicts"> + <title>Resolving Conflicts</title> + + <indexterm> + <primary>cvs</primary> + <secondary>resolving conflicts</secondary> + </indexterm> + + <para> + If you modify a file and the same content is modified by someone else + and committed first, you will probably see a message similar to the + following when committing the file or updating your local copy of the + module: + </para> + +<screen> +<computeroutput> +RCS file: /usr/local/CVS/docs/module-name/filename.sgml,v +retrieving revision 1.12 +retrieving revision 1.13 +Merging differences between 1.12 and 1.13 into filename.sgml +rcsmerge: warning: conflicts during merge +cvs server: conflicts found in filename.sgml +C filename.sgml +</computeroutput> +</screen> + + <para> + To resolve the conflict, open the file, search for + <computeroutput><<<<<<<</computeroutput> and determine which version + of the content should be in the latest revision of the file in + CVS. For example: + </para> +<screen> +<computeroutput> +<para> +Some sentence. +<<<<<<< filename.sgml +A sentence that was changed in the working copy. +======= +A same sentence that was changed differently and committed. +>>>>>>> 1.13 +</para> +</computeroutput> +</screen> + + <para> + The content between the + <computeroutput><<<<<<<</computeroutput>, the + <computeroutput>=======</computeroutput> is the content in your + working copy. The content between the + <computeroutput>=======</computeroutput> and the + <computeroutput>>>>>>>></computeroutput> is + the content from the latest revision (or the latest revision + for the branch) on the server. + </para> + + <para> + Resolve the conflict, and commit the file. + </para> + + </sect2> + + + <sect2 id="s2-cvs-cvscommands-summary"> + <title>Summary</title> + + <indexterm> + <primary>cvs</primary> + <secondary>commands</secondary> + <tertiary>summary of</tertiary> + </indexterm> + + <para> + All commands assume you are in the proper directory for the CVS module. + </para> + + <table frame="all" id="tb-cvs-basic-commands"> + <title>Basic CVS Commands</title> + <tgroup cols="2"> + <colspec colnum="1" colname="shortcut" colwidth="30"/> + <colspec colnum="2" colname="description" colwidth="60"/> + <thead> + <row> + <entry>Command</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>cvs checkout + <replaceable><module-name></replaceable></command> + or <command>cvs co <replaceable><module-name></replaceable></command></entry> + <entry>Creates a directory called + <replaceable><module-name></replaceable> with the contents of the + module in the directory</entry> + </row> + <row> + <entry><command>cvs co -d <replaceable><directory></replaceable> -r <replaceable><branchname></replaceable> <replaceable><module-name></replaceable></command></entry> + <entry>Creates the <replaceable><directory></replaceable> directory + with the contents of the <replaceable><branchname></replaceable> + branch of the <replaceable><module-name></replaceable> module</entry> + </row> + <row> + <entry><command>cvs update</command> or <command>cvs up</command></entry> + <entry>Update your files with the latest files from the CVS server</entry> + </row> + <row> + <entry><command>cvs add <replaceable><filename></replaceable></command></entry> + <entry>Add a new file "filename" to the CVS server</entry> + </row> + <row> + <entry><command>cvs commit -m "My message" + <replaceable><filename></replaceable></command></entry> + <entry>Update file <replaceable><filename></replaceable> with the + latest copy from your computer</entry> + </row> + <row> + <entry><command>cvs log <replaceable><filename></replaceable></command></entry> + <entry>View the commit messages for the file <replaceable><filename></replaceable></entry> + </row> + <row> + <entry><command>cvs status <replaceable><filename></replaceable></command></entry> + <entry>View status of the file, such as <computeroutput>Locally + Modified</computeroutput></entry> + </row> + <row> + <entry><command>cvs status -v <replaceable><filename></replaceable></command></entry> + <entry>View existing tags and branches for file</entry> + </row> + <row> + <entry><command>cvs diff <replaceable><filename></replaceable></command></entry> + <entry>Show diff of the working copy of the file and the latest + version of the file for the branch</entry> + </row> + <row> + <entry><command>cvs diff -r1.1 -r1.2 <replaceable><filename></replaceable></command></entry> + <entry>Show diff of version 1.1 and 1.2 for file</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + For more information, read the CVS manual available on your system at + <filename>/usr/share/doc/cvs-<replaceable><version-number></replaceable>/cvs.ps</filename> + (the CVS version might vary) and visit the CVS webpage available at + <ulink url="http://www.cvshome.org/">http://www.cvshome.org/</ulink>. + </para> + + <tip> + <title>Tip</title> + <para> + Since CVS is using ssh to connect to the CVS server, it will prompt + you for your password before allowing you to performing your CVS + request. If you want to configure your machine so that you do not + have to enter a password, refer to the <ulink + url="http://redhat.com/docs/manuals/linux/RHL-9-Manual/custom-guide/s1-openssh-client-config.html"><citetitle>&RH; Linux + 9 Customization Guide</citetitle></ulink> for details about using + <command>ssh-agent</command>. + </para> + </tip> + + </sect2> + + </sect1> + + </chapter> + + + + + + + + |