mirror of
https://github.com/glfs-book/glfs.git
synced 2025-07-22 01:12:59 +00:00
b6e0053e6a
The application tag seemed to just put an extra space on either side of the word(s) the tags surrounded and seemed to serve no purpose beyond that. If it served the purpose of jhalfs, well this book is not supported by jhalfs. The result of the tags just added space in both the rendered output and in the XML files. Now, when referring to a package name, we just say the name and don't surround it via a tag. The only exception is using <command>, <filename>, <xref>, or <ulink>.
448 lines
16 KiB
XML
448 lines
16 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
|
<!ENTITY % general-entities SYSTEM "../../general.ent">
|
|
%general-entities;
|
|
|
|
<!ENTITY git-root "&kernel-dl;/software/scm/git" >
|
|
|
|
<!ENTITY git-download-http "&git-root;/git-&git-version;.tar.xz">
|
|
<!ENTITY git-download-ftp " ">
|
|
]>
|
|
|
|
<sect1 id="git" xreflabel="git-&git-version;">
|
|
<?dbhtml filename="git.html"?>
|
|
|
|
<title>Git-&git-version;</title>
|
|
|
|
<indexterm zone="git">
|
|
<primary sortas="a-Git">Git</primary>
|
|
</indexterm>
|
|
|
|
<sect2 role="package">
|
|
<title>Introduction to Git</title>
|
|
|
|
<para>
|
|
Git is a free and open source, distributed
|
|
version control system designed to handle everything from small to very
|
|
large projects with speed and efficiency. Every
|
|
Git clone is a full-fledged repository with
|
|
complete history and full revision tracking capabilities, not dependent
|
|
on network access or a central server. Branching and merging are fast and
|
|
easy to do. Git is used for version control of
|
|
files, much like tools such as Mercurial,
|
|
Bazaar, Subversion,
|
|
<ulink url="https://www.nongnu.org/cvs/">CVS</ulink>,
|
|
Perforce, and
|
|
Team Foundation Server.
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
Download (HTTP): <ulink url="&git-download-http;"/>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Download (FTP): <ulink url="&git-download-ftp;"/>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<bridgehead renderas="sect3">Additional Downloads</bridgehead>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
<ulink url="&git-root;/git-manpages-&git-version;.tar.xz">
|
|
&git-root;/git-manpages-&git-version;.tar.xz</ulink>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="&git-root;/git-htmldocs-&git-version;.tar.xz">
|
|
&git-root;/git-htmldocs-&git-version;.tar.xz</ulink>
|
|
and other docs
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<bridgehead renderas="sect3">Git Dependencies</bridgehead>
|
|
|
|
<bridgehead renderas="sect4">Recommended</bridgehead>
|
|
<para role="recommended">
|
|
<xref linkend="curl"/> (needed to use Git over
|
|
http, https, ftp or ftps)
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 role="installation">
|
|
<title>Installation of Git</title>
|
|
|
|
<para>
|
|
Install Git by running the following
|
|
commands:
|
|
</para>
|
|
|
|
<screen><userinput>./configure --prefix=/usr \
|
|
--with-gitconfig=/etc/gitconfig \
|
|
--with-python=python3 &&
|
|
make</userinput></screen>
|
|
|
|
<!--
|
|
<para>
|
|
The test suite can be run in parallel mode. To run the test suite, issue:
|
|
<command>make test -k |& tee test.log</command>. If some test
|
|
fails, the list of failed tests can be shown via
|
|
<command>grep '^not ok' test.log | grep -v TODO</command>.
|
|
<!- - It looks like I'd misdiagnosed the issue. - ->
|
|
<!- -phrase revision='systemd'>One test named <literal>start and stop
|
|
Linux/systemd maintenance</literal> is known to fail if the current
|
|
login session is not started after rebuilding
|
|
<xref linkend='systemd'/> with <xref linkend='linux-pam'/>
|
|
support, or it's a SSH session but the SSH server is not configured
|
|
with <option>UsePAM</option> enabled.</phrase- ->
|
|
</para>
|
|
-->
|
|
|
|
<para>
|
|
Now, as the <systemitem class="username">root</systemitem>
|
|
user:
|
|
</para>
|
|
|
|
<screen role="root"><userinput>make perllibdir=/usr/lib/perl5/&lfs-perl-version;/site_perl install</userinput></screen>
|
|
|
|
<bridgehead renderas="sect3">If you downloaded the man pages and/or html docs</bridgehead>
|
|
|
|
<para>
|
|
If you downloaded the man pages untar them as the
|
|
<systemitem class="username">root</systemitem> user:
|
|
</para>
|
|
|
|
<screen role="root"><userinput>tar -xf ../git-manpages-&git-version;.tar.xz \
|
|
-C /usr/share/man --no-same-owner --no-overwrite-dir</userinput></screen>
|
|
|
|
<para>
|
|
If you downloaded the html docs untar them as the
|
|
<systemitem class="username">root</systemitem> user:
|
|
</para>
|
|
|
|
<screen role="root"><userinput>mkdir -vp /usr/share/doc/git-&git-version; &&
|
|
tar -xf ../git-htmldocs-&git-version;.tar.xz \
|
|
-C /usr/share/doc/git-&git-version; --no-same-owner --no-overwrite-dir &&
|
|
|
|
find /usr/share/doc/git-&git-version; -type d -exec chmod 755 {} \; &&
|
|
find /usr/share/doc/git-&git-version; -type f -exec chmod 644 {} \;</userinput></screen>
|
|
|
|
<!-- ==== Reorganize docs ====== -->
|
|
<bridgehead renderas="sect3">Reorganize text and html in the html-docs</bridgehead>
|
|
|
|
<para>
|
|
The html-docs include a lot of plain text files.
|
|
Reorganize the files as the
|
|
<systemitem class="username">root</systemitem> user:
|
|
</para>
|
|
|
|
<screen role="root"><userinput>mkdir -vp /usr/share/doc/git-&git-version;/man-pages/{html,text} &&
|
|
mv /usr/share/doc/git-&git-version;/{git*.adoc,man-pages/text} &&
|
|
mv /usr/share/doc/git-&git-version;/{git*.,index.,man-pages/}html &&
|
|
|
|
mkdir -vp /usr/share/doc/git-&git-version;/technical/{html,text} &&
|
|
mv /usr/share/doc/git-&git-version;/technical/{*.adoc,text} &&
|
|
mv /usr/share/doc/git-&git-version;/technical/{*.,}html &&
|
|
|
|
mkdir -vp /usr/share/doc/git-&git-version;/howto/{html,text} &&
|
|
mv /usr/share/doc/git-&git-version;/howto/{*.adoc,text} &&
|
|
mv /usr/share/doc/git-&git-version;/howto/{*.,}html &&
|
|
|
|
sed -i '/^<a href=/s|howto/|&html/|' /usr/share/doc/git-&git-version;/howto-index.html &&
|
|
sed -i '/^\* link:/s|howto/|&html/|' /usr/share/doc/git-&git-version;/howto-index.adoc</userinput></screen>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Using Git</title>
|
|
|
|
<para>
|
|
This Git installation doesn't have the full power Git can provide, such
|
|
as scheduling and the like. If you want even more features, check
|
|
<ulink url="&blfs-svn;/general/git.html"/>. However, this installation
|
|
if you installed <xref linkend="curl"/> can provide enough features to
|
|
be of good use for you, such as the ability to clone repos. This is
|
|
sometimes a necessity when developers don't publish releases or haven't
|
|
in a long time, so the repo is the only way to obtain the (hopefully) up
|
|
to date package. In order to clone a repo, simply invoke:
|
|
</para>
|
|
|
|
<screen><userinput>git clone https://path/to/repo.git</userinput></screen>
|
|
|
|
<para>
|
|
The above command will then clone the entire repository besides
|
|
subprojects, something that some projects do and require special instructions.
|
|
A directory will be created, called <filename>repo</filename>, in the current
|
|
working directory, with all the repo's files being in that just created
|
|
directory. If you want to for some reason change the directory name, you
|
|
can do it when you clone the repo, like so:
|
|
</para>
|
|
|
|
<screen><userinput>git clone https://path/to/repo.git newname</userinput></screen>
|
|
|
|
<para>
|
|
The above command will create the directory called <filename>newname
|
|
</filename> and put all the repo's files in that directory. Eventually you'll
|
|
come across a repository that has some subprojects, for instance an
|
|
emulator that depends on graphic libraries and intends to compile a static
|
|
version of it. In order to pull in those subprojects, you must also
|
|
invoke the <parameter>--recurse-submodules</parameter> option. This will
|
|
clone all the subprojects and check them out.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Git Repo vs Release Archives</title>
|
|
|
|
<para>
|
|
Most of the packaged source code in GLFS are packaged in
|
|
tarballs or zipfiles. These tarballs and zipfiles were created
|
|
as part of a release, and often include files not found in the repo
|
|
equivalent where the package development happens. Usually the extra
|
|
included files are the configure scripts you should now be used to using.
|
|
They are generated manually using <command>aclocal</command>,
|
|
<command>autoconf</command>, and <command>automake</command>. The
|
|
configure scripts are often not in the repos, so if the git repo gets
|
|
cloned, you will have to generate the configure script yourself if you
|
|
find <filename>configure.ac</filename>, <filename>Makefile.am</filename>,
|
|
and possibly <filename>autogen.sh</filename>. You won't need to do this
|
|
if you find the repo has a <filename>Makefile</filename>,
|
|
<filename>meson_options.txt</filename>, or
|
|
<filename>CMakeLists.txt</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
Another big difference between the repo and the release package is that
|
|
the repo probably has had commits after the last release if it had any,
|
|
and new commits can introduce bugs or prevent compilation. When developers
|
|
prepare a new release, often they search for issues, bugs, and compilation
|
|
errors, making it stable before they publish the release and its related
|
|
package files. Release packages aren't entirely safe from issues and can
|
|
help with causing issues as files can be added. Sometimes you can tell
|
|
if something is wrong, sometimes you can't. It's always important to be
|
|
up to date with security news to prevent damage.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 role="commands">
|
|
<title>Command Explanations</title>
|
|
|
|
&options-configure;
|
|
|
|
<para>
|
|
<parameter>--with-gitconfig=/etc/gitconfig</parameter>: This sets
|
|
<filename>/etc/gitconfig</filename> as the file that stores
|
|
the default, system wide, Git
|
|
settings.
|
|
</para>
|
|
|
|
<para>
|
|
<parameter>--with-python=python3</parameter>: Use this switch to use
|
|
Python 3, instead of the EOL'ed
|
|
Python 2. Python is used for the
|
|
<command>git p4</command> interface to Perforce repositories,
|
|
and also used in some tests.
|
|
</para>
|
|
|
|
<!--
|
|
<para>
|
|
<option>- -with-libpcre2</option>: Use this switch if
|
|
PCRE2 is installed.
|
|
</para>
|
|
-->
|
|
|
|
<para>
|
|
<command>tar -xf ../git-manpages-&git-version;.tar.gz -C
|
|
/usr/share/man --no-same-owner</command>: This untars
|
|
<filename>git-manpages-&git-version;.tar.gz</filename>. The
|
|
<option>-C</option> option makes tar change directory to
|
|
<filename class="directory">/usr/share/man</filename> before
|
|
it starts to decompress the docs. The <option>--no-same-owner</option>
|
|
option stops tar from preserving the user and group details of the
|
|
files. This is useful as that user or group may not exist on your
|
|
system; this could (potentially) be a security risk.
|
|
</para>
|
|
|
|
<para>
|
|
<command>mv /usr/share/doc/git-&git-version; ...</command>: These
|
|
commands move some of the files into subfolders to make it easier to sort
|
|
through the docs and find what you're looking for.
|
|
</para>
|
|
|
|
<para>
|
|
<command>find ... chmod ...</command>: These commands correct the
|
|
permissions in the shipped documentation tar file.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 role="configuration">
|
|
<title>Configuring Git</title>
|
|
|
|
<sect3 id="git-config">
|
|
<title>Config Files</title>
|
|
<para>
|
|
<filename>~/.gitconfig</filename> and
|
|
<filename>/etc/gitconfig</filename>
|
|
</para>
|
|
|
|
<indexterm zone="git git-config">
|
|
<primary sortas="e-AA.gitconfig">~/.gitconfig</primary>
|
|
</indexterm>
|
|
|
|
<indexterm zone="git git-config">
|
|
<primary sortas="e-etc-gitconfig">/etc/gitconfig</primary>
|
|
</indexterm>
|
|
|
|
</sect3>
|
|
|
|
</sect2>
|
|
|
|
<sect2 role="content">
|
|
<title>Contents</title>
|
|
|
|
<segmentedlist>
|
|
<segtitle>Installed Programs</segtitle>
|
|
<segtitle>Installed Libraries</segtitle>
|
|
<segtitle>Installed Directories</segtitle>
|
|
|
|
<seglistitem>
|
|
<seg>
|
|
git, git-receive-pack, git-upload-archive, and
|
|
git-upload-pack (hardlinked to each
|
|
other), git-cvsserver, git-shell, gitk, and scalar
|
|
</seg>
|
|
<seg>
|
|
None
|
|
</seg>
|
|
<seg>
|
|
/usr/libexec/git-core,
|
|
/usr/lib/perl5/&lfs-perl-version;/site_perl/Git, and
|
|
/usr/share/{doc/git-&git-version;,git-core,git-gui,gitk,gitweb}
|
|
</seg>
|
|
</seglistitem>
|
|
</segmentedlist>
|
|
|
|
<variablelist>
|
|
<bridgehead renderas="sect3">Short Descriptions</bridgehead>
|
|
<?dbfo list-presentation="list"?>
|
|
<?dbhtml list-presentation="table"?>
|
|
|
|
<varlistentry id="git-prog">
|
|
<term><command>git</command></term>
|
|
<listitem>
|
|
<para>
|
|
is the stupid content tracker
|
|
</para>
|
|
<indexterm zone="git git-prog">
|
|
<primary sortas="b-git">git</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="git-cvsserver">
|
|
<term><command>git-cvsserver</command></term>
|
|
<listitem>
|
|
<para>
|
|
is a CVS server emulator for Git
|
|
</para>
|
|
<indexterm zone="git git-cvsserver">
|
|
<primary sortas="b-git-cvsserver">git-cvsserver</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="gitk">
|
|
<term><command>gitk</command></term>
|
|
<listitem>
|
|
<para>
|
|
is a graphical Git repository browser
|
|
(needs <ulink url="&blfs-svn;/general/tk.html">Tk</ulink>)
|
|
</para>
|
|
<indexterm zone="git gitk">
|
|
<primary sortas="b-gitk">gitk</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="git-receive-pack">
|
|
<term><command>git-receive-pack</command></term>
|
|
<listitem>
|
|
<para>
|
|
is invoked by <command>git send-pack</command> and updates the
|
|
repository with the information fed from the remote end
|
|
</para>
|
|
<indexterm zone="git git-receive-pack">
|
|
<primary sortas="b-git-receive-pack">git-receive-pack</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="git-shell">
|
|
<term><command>git-shell</command></term>
|
|
<listitem>
|
|
<para>
|
|
is a login shell for SSH accounts to provide restricted Git
|
|
access
|
|
</para>
|
|
<indexterm zone="git git-shell">
|
|
<primary sortas="b-git-shell">git-shell</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="git-upload-archive">
|
|
<term><command>git-upload-archive</command></term>
|
|
<listitem>
|
|
<para>
|
|
is invoked by <command>git archive --remote</command> and sends
|
|
a generated archive to the other end over the git protocol
|
|
</para>
|
|
<indexterm zone="git git-upload-archive">
|
|
<primary sortas="b-git-upload-archive">git-upload-archive</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="git-upload-pack">
|
|
<term><command>git-upload-pack</command></term>
|
|
<listitem>
|
|
<para>
|
|
is invoked by <command>git fetch-pack</command>, it discovers
|
|
what objects the other side is missing, and sends them after
|
|
packing
|
|
</para>
|
|
<indexterm zone="git git-upload-pack">
|
|
<primary sortas="b-git-upload-pack">git-upload-pack</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="scalar">
|
|
<term><command>scalar</command></term>
|
|
<listitem>
|
|
<para>
|
|
is a repository management tool that optimizes Git for use in
|
|
large repositories
|
|
</para>
|
|
<indexterm zone="git scalar">
|
|
<primary sortas="b-scalar">scalar</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|