comparison en/ch05-collab.xml @ 775:29f0f79cf614

Update paragraph IDs

774:e6c99cbd0abd

    <para id="x_450">If you're interested in providing a web interface
      to your own repositories, there are several good ways to do
      this.</para>

    <para>The easiest and fastest way to get started in an informal
      environment is to use the <command role="hg-cmd">hg
	serve</command> command, which is best suited to short-term
      <quote>lightweight</quote> serving.  See <xref
	linkend="sec:collab:serve"/> below for details of how to use
      this command.</para>

    <para>For longer-lived repositories that you'd like to have
      permanently available, there are several public hosting services
      available.</para>

    <itemizedlist>
      <listitem>
	<para>Bitbucket, at <ulink
	    url="http://bitbucket.org/">http://bitbucket.org/</ulink>,
	  provides free hosting for open source projects, and paid
	  hosting for commercial projects.</para>
      </listitem>
    </itemizedlist>

    <para>If you would prefer to host your own repositories, Mercurial
      has built-in support for several popular hosting technologies,
      most notably CGI (Common Gateway Interface), and WSGI (Web
      Services Gateway Interface).  See <xref
	linkend="sec:collab:cgi"/> for details of CGI and WSGI
      configuration.</para>

    </sect2>

    <sect2>
      <title>A hosted central repository</title>

      <para>A wonderful thing about public hosting services like
	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
	not only do they handle the fiddly server configuration
	details, such as user accounts, authentication, and secure
	wire protocols, they provide additional infrastructure to make
	this model work well.</para>

      <para>For instance, a well-engineered hosting service will let
	people clone their own copies of a repository with a single
	click.  This lets people work in separate spaces and share
	their changes when they're ready.</para>

      <para>In addition, a good hosting service will let people
	communicate with each other, for instance to say <quote>there
	  are changes ready for you to review in this
	  tree</quote>.</para>
    </sect2>

	recommend generating a key pair.</para>

      <tip>
	<title>Key pairs are not mandatory</title>

	<para>Mercurial knows nothing about ssh authentication or key
	  pairs.  You can, if you like, safely ignore this section and
	  the one that follows until you grow tired of repeatedly
	  typing ssh passwords.</para>
      </tip>

      <itemizedlist>
	<listitem>
	  <para>On a Unix-like system, the
	    <command>ssh-keygen</command> command will do the
	    trick.</para>
	  <para>On Windows, if you're using TortoiseHg, you may need
	    to download a command named <command>puttygen</command>
	    from <ulink
	      url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 
	      PuTTY web site</ulink> to generate a key pair.  See
	    <ulink

	    automatically for you when you log in.  You'll need to use
	    the <command>ssh-add</command> command to add passphrases
	    to the agent's store.</para>
	</listitem>
	<listitem>
	  <para>On Windows, if you're using TortoiseHg, the
	    <command>pageant</command> command acts as the agent.  As
	    with <command>puttygen</command>, you'll need to <ulink
	      url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 
	      <command>pageant</command></ulink> from the PuTTY web
	    site and read <ulink

  </sect1>

  <sect1 id="sec:collab:cgi">
    <title>Serving over HTTP using CGI</title>

    <para>The simplest way to host one or more repositories in a
      permanent way is to use a web server and Mercurial's CGI
      support.</para>

    <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
      CGI interface can take anything from a few moments to several

	cases you will encounter. Please use your discretion and
	judgment in following the sections below.  Be prepared to make
	plenty of mistakes, and to spend a lot of time reading your
	server's error logs.</para>

      <para>If you don't have a strong stomach for tweaking
	configurations over and over, or a compelling need to host
	your own services, you might want to try one of the public
	hosting services that I mentioned earlier.</para>
    </note>

	      role="rc-item-web">style</envar>: Controls the template
	    Mercurial uses to display the web interface.  Mercurial
	    ships with several web templates.</para>
	  <itemizedlist>
	    <listitem>
	      <para><literal>coal</literal> is monochromatic.</para>
	    </listitem>
	    <listitem>
	      <para><literal>gitweb</literal> emulates the visual
		style of git's web interface.</para>
	    </listitem>
	    <listitem>
	      <para><literal>monoblue</literal> uses solid blues and
		greys.</para>
	    </listitem>
	    <listitem>
	      <para><literal>paper</literal> is the default.</para>
	    </listitem>
	    <listitem>
	      <para><literal>spartan</literal> was the default for a
		long time.</para>
	    </listitem>
	  </itemizedlist>
	  <para>You can
	    also specify a custom template of your own; see 
	    <xref linkend="chap:template"/> for details. Here, you can
	    see how to enable the <literal>gitweb</literal>
	    style.</para>
	  <programlisting>[web]

  </sect1>

  <sect1>
    <title>System-wide configuration</title>

    <para>On Unix-like systems shared by multiple users (such as a
      server to which people publish changes), it often makes sense to
      set up some global default behaviors, such as what theme to use
      in web interfaces.</para>

    <para>If a file named <filename>/etc/mercurial/hgrc</filename>
      exists, Mercurial will read it at startup time and apply any
      configuration settings it finds in that file.  It will also look
      for files ending in a <literal>.rc</literal> extension in a
      directory named <filename>/etc/mercurial/hgrc.d</filename>, and
      apply any configuration settings it finds in each of those
      files.</para>

    <sect2>
      <title>Making Mercurial more trusting</title>

      <para>One situation in which a global <filename>hgrc</filename>
	can be useful is if users are pulling changes owned by other
	users.  By default, Mercurial will not trust most of the
	configuration items in a <filename>.hg/hgrc</filename> file
	inside a repository that is owned by a different user. If we
	clone or pull changes from such a repository, Mercurial will
	print a warning stating that it does not trust their
	<filename>.hg/hgrc</filename>.</para>

      <para>If everyone in a particular Unix group is on the same team
	and <emphasis>should</emphasis> trust each other's
	configuration settings, or we want to trust particular users,
	we can override Mercurial's skeptical defaults by creating a
	system-wide <filename>hgrc</filename> file such as the
	following:</para>

775:29f0f79cf614

    <para id="x_450">If you're interested in providing a web interface
      to your own repositories, there are several good ways to do
      this.</para>

    <para id="x_69d">The easiest and fastest way to get started in an informal
      environment is to use the <command role="hg-cmd">hg
	serve</command> command, which is best suited to short-term
      <quote>lightweight</quote> serving.  See <xref
	linkend="sec:collab:serve"/> below for details of how to use
      this command.</para>

    <para id="x_69e">For longer-lived repositories that you'd like to have
      permanently available, there are several public hosting services
      available.</para>

    <itemizedlist>
      <listitem>
	<para id="x_69f">Bitbucket, at <ulink
	    url="http://bitbucket.org/">http://bitbucket.org/</ulink>,
	  provides free hosting for open source projects, and paid
	  hosting for commercial projects.</para>
      </listitem>
    </itemizedlist>

    <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
      has built-in support for several popular hosting technologies,
      most notably CGI (Common Gateway Interface), and WSGI (Web
      Services Gateway Interface).  See <xref
	linkend="sec:collab:cgi"/> for details of CGI and WSGI
      configuration.</para>

    </sect2>

    <sect2>
      <title>A hosted central repository</title>

      <para id="x_6a1">A wonderful thing about public hosting services like
	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
	not only do they handle the fiddly server configuration
	details, such as user accounts, authentication, and secure
	wire protocols, they provide additional infrastructure to make
	this model work well.</para>

      <para id="x_6a2">For instance, a well-engineered hosting service will let
	people clone their own copies of a repository with a single
	click.  This lets people work in separate spaces and share
	their changes when they're ready.</para>

      <para id="x_6a3">In addition, a good hosting service will let people
	communicate with each other, for instance to say <quote>there
	  are changes ready for you to review in this
	  tree</quote>.</para>
    </sect2>

	recommend generating a key pair.</para>

      <tip>
	<title>Key pairs are not mandatory</title>

	<para id="x_6a4">Mercurial knows nothing about ssh authentication or key
	  pairs.  You can, if you like, safely ignore this section and
	  the one that follows until you grow tired of repeatedly
	  typing ssh passwords.</para>
      </tip>

      <itemizedlist>
	<listitem>
	  <para id="x_6a5">On a Unix-like system, the
	    <command>ssh-keygen</command> command will do the
	    trick.</para>
	  <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
	    to download a command named <command>puttygen</command>
	    from <ulink
	      url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 
	      PuTTY web site</ulink> to generate a key pair.  See
	    <ulink

	    automatically for you when you log in.  You'll need to use
	    the <command>ssh-add</command> command to add passphrases
	    to the agent's store.</para>
	</listitem>
	<listitem>
	  <para id="x_6a7">On Windows, if you're using TortoiseHg, the
	    <command>pageant</command> command acts as the agent.  As
	    with <command>puttygen</command>, you'll need to <ulink
	      url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 
	      <command>pageant</command></ulink> from the PuTTY web
	    site and read <ulink

  </sect1>

  <sect1 id="sec:collab:cgi">
    <title>Serving over HTTP using CGI</title>

    <para id="x_6a8">The simplest way to host one or more repositories in a
      permanent way is to use a web server and Mercurial's CGI
      support.</para>

    <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
      CGI interface can take anything from a few moments to several

	cases you will encounter. Please use your discretion and
	judgment in following the sections below.  Be prepared to make
	plenty of mistakes, and to spend a lot of time reading your
	server's error logs.</para>

      <para id="x_6a9">If you don't have a strong stomach for tweaking
	configurations over and over, or a compelling need to host
	your own services, you might want to try one of the public
	hosting services that I mentioned earlier.</para>
    </note>

	      role="rc-item-web">style</envar>: Controls the template
	    Mercurial uses to display the web interface.  Mercurial
	    ships with several web templates.</para>
	  <itemizedlist>
	    <listitem>
	      <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
	    </listitem>
	    <listitem>
	      <para id="x_6ab"><literal>gitweb</literal> emulates the visual
		style of git's web interface.</para>
	    </listitem>
	    <listitem>
	      <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
		greys.</para>
	    </listitem>
	    <listitem>
	      <para id="x_6ad"><literal>paper</literal> is the default.</para>
	    </listitem>
	    <listitem>
	      <para id="x_6ae"><literal>spartan</literal> was the default for a
		long time.</para>
	    </listitem>
	  </itemizedlist>
	  <para id="x_6af">You can
	    also specify a custom template of your own; see 
	    <xref linkend="chap:template"/> for details. Here, you can
	    see how to enable the <literal>gitweb</literal>
	    style.</para>
	  <programlisting>[web]

  </sect1>

  <sect1>
    <title>System-wide configuration</title>

    <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
      server to which people publish changes), it often makes sense to
      set up some global default behaviors, such as what theme to use
      in web interfaces.</para>

    <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
      exists, Mercurial will read it at startup time and apply any
      configuration settings it finds in that file.  It will also look
      for files ending in a <literal>.rc</literal> extension in a
      directory named <filename>/etc/mercurial/hgrc.d</filename>, and
      apply any configuration settings it finds in each of those
      files.</para>

    <sect2>
      <title>Making Mercurial more trusting</title>

      <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
	can be useful is if users are pulling changes owned by other
	users.  By default, Mercurial will not trust most of the
	configuration items in a <filename>.hg/hgrc</filename> file
	inside a repository that is owned by a different user. If we
	clone or pull changes from such a repository, Mercurial will
	print a warning stating that it does not trust their
	<filename>.hg/hgrc</filename>.</para>

      <para id="x_6b3">If everyone in a particular Unix group is on the same team
	and <emphasis>should</emphasis> trust each other's
	configuration settings, or we want to trust particular users,
	we can override Mercurial's skeptical defaults by creating a
	system-wide <filename>hgrc</filename> file such as the
	following:</para>