Commit 66afe50b authored by Junio C Hamano's avatar Junio C Hamano

Merge branch 'ta/doc-cleanup' into maint

* ta/doc-cleanup:
  Documentation: build html for all files in technical and howto
  Documentation/howto: convert plain text files to asciidoc
  Documentation/technical: convert plain text files to asciidoc
  Change headline of technical/send-pack-pipeline.txt to not confuse its content with content from git-send-pack.txt
  Shorten two over-long lines in git-bisect-lk2009.txt by abbreviating some sha1
  Split over-long synopsis in git-fetch-pack.txt into several lines
parents 854dfda8 5e00439f
......@@ -24,8 +24,30 @@ SP_ARTICLES = user-manual
SP_ARTICLES += howto/revert-branch-rebase
SP_ARTICLES += howto/using-merge-subtree
SP_ARTICLES += howto/using-signed-tag-in-pull-request
SP_ARTICLES += howto/use-git-daemon
SP_ARTICLES += howto/update-hook-example
SP_ARTICLES += howto/setup-git-server-over-http
SP_ARTICLES += howto/separating-topic-branches
SP_ARTICLES += howto/revert-a-faulty-merge
SP_ARTICLES += howto/recover-corrupted-blob-object
SP_ARTICLES += howto/rebuild-from-update-hook
SP_ARTICLES += howto/rebuild-from-update-hook
SP_ARTICLES += howto/rebase-from-internal-branch
SP_ARTICLES += howto/maintain-git
API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
SP_ARTICLES += $(API_DOCS)
TECH_DOCS = technical/index-format
TECH_DOCS += technical/pack-format
TECH_DOCS += technical/pack-heuristics
TECH_DOCS += technical/pack-protocol
TECH_DOCS += technical/protocol-capabilities
TECH_DOCS += technical/protocol-common
TECH_DOCS += technical/racy-git
TECH_DOCS += technical/send-pack-pipeline
TECH_DOCS += technical/shallow
TECH_DOCS += technical/trivial-merge
SP_ARTICLES += $(TECH_DOCS)
SP_ARTICLES += technical/api-index
DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
......@@ -231,7 +253,7 @@ clean:
$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
$(RM) *.pdf
$(RM) howto-index.txt howto/*.html doc.dep
$(RM) technical/api-*.html technical/api-index.txt
$(RM) technical/*.html technical/api-index.txt
$(RM) $(cmds_txt) *.made
$(RM) manpage-base-url.xsl
......@@ -264,7 +286,7 @@ technical/api-index.txt: technical/api-index-skel.txt \
$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
$(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt
$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
......
......@@ -257,7 +257,7 @@ Date: Sat May 3 11:59:44 2008 -0700
Linux 2.6.26-rc1
:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M Makefile
:100644 100644 5cf82581... 4492984e... M Makefile
-------------
At this point we can see what the commit does, check it out (if it's
......@@ -331,7 +331,7 @@ Date: Sat May 3 11:59:44 2008 -0700
Linux 2.6.26-rc1
:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M Makefile
:100644 100644 5cf82581... 4492984e... M Makefile
bisect run success
-------------
......
......@@ -9,7 +9,10 @@ git-fetch-pack - Receive missing objects from another repository
SYNOPSIS
--------
[verse]
'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...]
'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag]
[--upload-pack=<git-upload-pack>]
[--depth=<n>] [--no-progress]
[-v] [<host>:]<directory> [<refs>...]
DESCRIPTION
-----------
......
......@@ -5,6 +5,10 @@ Abstract: Imagine that git development is racing along as usual, when our friend
neighborhood maintainer is struck down by a wayward bus. Out of the
hordes of suckers (loyal developers), you have been tricked (chosen) to
step up as the new maintainer. This howto will show you "how to" do it.
Content-type: text/asciidoc
How to maintain Git
===================
The maintainer's git time is spent on three activities.
......
......@@ -8,7 +8,12 @@ Abstract: In this article, JC talks about how he rebases the
the "master" branch, and how "rebase" works. Also discussed
is how this applies to individual developers who sends patches
upstream.
Content-type: text/asciidoc
How to rebase from an internal branch
=====================================
--------------------------------------
Petr Baudis <[email protected]> writes:
> Dear diary, on Sun, Aug 14, 2005 at 09:57:13AM CEST, I got a letter
......@@ -19,6 +24,7 @@ Petr Baudis <[email protected]> writes:
>> > branch to the real branches.
>>
> Actually, wouldn't this be also precisely for what StGIT is intended to?
--------------------------------------
Exactly my feeling. I was sort of waiting for Catalin to speak
up. With its basing philosophical ancestry on quilt, this is
......@@ -156,8 +162,3 @@ you continue on starting from the new "master" head, which is
the #1' commit.
-jc
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
......@@ -5,6 +5,10 @@ Date: Fri, 26 Aug 2005 18:19:10 -0700
Abstract: In this how-to article, JC talks about how he
uses the post-update hook to automate git documentation page
shown at http://www.kernel.org/pub/software/scm/git/docs/.
Content-type: text/asciidoc
How to rebuild from update hook
===============================
The pages under http://www.kernel.org/pub/software/scm/git/docs/
are built from Documentation/ directory of the git.git project
......
......@@ -3,11 +3,17 @@ From: Linus Torvalds <[email protected]>
Subject: corrupt object on git-gc
Abstract: Some tricks to reconstruct blob objects in order to fix
a corrupted repository.
Content-type: text/asciidoc
How to recover a corrupted blob object
======================================
-----------------------------------------------------------
On Fri, 9 Nov 2007, Yossi Leybovich wrote:
>
> Did not help still the repository look for this object?
> Any one know how can I track this object and understand which file is it
-----------------------------------------------------------
So exactly *because* the SHA1 hash is cryptographically secure, the hash
itself doesn't actually tell you anything, in order to fix a corrupt
......@@ -31,19 +37,23 @@ original object, so right now the corrupt object is useless, but it's very
interesting for the future, in the hope that you can re-create a
non-corrupt version.
-----------------------------------------------------------
So:
> ib]$ mv .git/objects/4b/9458b3786228369c63936db65827de3cc06200 ../
-----------------------------------------------------------
This is the right thing to do, although it's usually best to save it under
it's full SHA1 name (you just dropped the "4b" from the result ;).
Let's see what that tells us:
-----------------------------------------------------------
> ib]$ git-fsck --full
> broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
> to blob 4b9458b3786228369c63936db65827de3cc06200
> missing blob 4b9458b3786228369c63936db65827de3cc06200
-----------------------------------------------------------
Ok, I removed the "dangling commit" messages, because they are just
messages about the fact that you probably have rebased etc, so they're not
......
......@@ -7,6 +7,10 @@ Abstract: Sometimes a branch that was already merged to the mainline
after the offending branch is fixed.
Message-ID: <[email protected]>
References: <[email protected]>
Content-type: text/asciidoc
How to revert a faulty merge
============================
Alan <[email protected]> said:
......
......@@ -8,8 +8,8 @@ Date: Mon, 29 Aug 2005 21:39:02 -0700
Content-type: text/asciidoc
Message-ID: <[email protected]>
Reverting an existing commit
============================
How to revert an existing commit
================================
One of the changes I pulled into the 'master' branch turns out to
break building GIT with GCC 2.95. While they were well intentioned
......
From: Junio C Hamano <[email protected]>
Subject: Separating topic branches
Abstract: In this article, JC describes how to separate topic branches.
Content-type: text/asciidoc
How to separate topic branches
==============================
This text was originally a footnote to a discussion about the
behaviour of the git diff commands.
......
From: Rutger Nijlunsing <[email protected]>
Subject: Setting up a git repository which can be pushed into and pulled from over HTTP(S).
Date: Thu, 10 Aug 2006 22:00:26 +0200
Content-type: text/asciidoc
How to setup git server over http
=================================
Since Apache is one of those packages people like to compile
themselves while others prefer the bureaucrat's dream Debian, it is
......
......@@ -5,6 +5,10 @@ Message-ID: <[email protected]>
Abstract: An example hooks/update script is presented to
implement repository maintenance policies, such as who can push
into which branch and who can make a tag.
Content-type: text/asciidoc
How to use the update hook
==========================
When your developer runs git-push into the repository,
git-receive-pack is run (either locally or over ssh) as that
......@@ -32,8 +36,7 @@ like this as your hooks/update script.
[jc: editorial note. This is a much improved version by Carl
since I posted the original outline]
-- >8 -- beginning of script -- >8 --
----------------------------------------------------
#!/bin/bash
umask 002
......@@ -111,12 +114,12 @@ then
info "Found matching head pattern: '$head_pattern'"
for user_pattern in $user_patterns; do
info "Checking user: '$username' against pattern: '$user_pattern'"
matchlen=$(expr "$username" : "$user_pattern")
if test "$matchlen" = "${#username}"
then
grant "Allowing user: '$username' with pattern: '$user_pattern'"
fi
info "Checking user: '$username' against pattern: '$user_pattern'"
matchlen=$(expr "$username" : "$user_pattern")
if test "$matchlen" = "${#username}"
then
grant "Allowing user: '$username' with pattern: '$user_pattern'"
fi
done
deny "The user is not in the access list for this branch"
done
......@@ -149,13 +152,13 @@ then
info "Found matching head pattern: '$head_pattern'"
for group_pattern in $group_patterns; do
for groupname in $groups; do
info "Checking group: '$groupname' against pattern: '$group_pattern'"
matchlen=$(expr "$groupname" : "$group_pattern")
if test "$matchlen" = "${#groupname}"
then
grant "Allowing group: '$groupname' with pattern: '$group_pattern'"
fi
for groupname in $groups; do
info "Checking group: '$groupname' against pattern: '$group_pattern'"
matchlen=$(expr "$groupname" : "$group_pattern")
if test "$matchlen" = "${#groupname}"
then
grant "Allowing group: '$groupname' with pattern: '$group_pattern'"
fi
done
done
deny "None of the user's groups are in the access list for this branch"
......@@ -169,24 +172,21 @@ then
fi
deny >/dev/null "There are no more rules to check. Denying access"
-- >8 -- end of script -- >8 --
----------------------------------------------------
This uses two files, $GIT_DIR/info/allowed-users and
allowed-groups, to describe which heads can be pushed into by
whom. The format of each file would look like this:
refs/heads/master junio
+refs/heads/pu junio
refs/heads/cogito$ pasky
refs/heads/bw/.* linus
refs/heads/tmp/.* .*
refs/tags/v[0-9].* junio
refs/heads/master junio
+refs/heads/pu junio
refs/heads/cogito$ pasky
refs/heads/bw/.* linus
refs/heads/tmp/.* .*
refs/tags/v[0-9].* junio
With this, Linus can push or create "bw/penguin" or "bw/zebra"
or "bw/panda" branches, Pasky can do only "cogito", and JC can
do master and pu branches and make versioned tags. And anybody
can do tmp/blah branches. The '+' sign at the pu record means
that JC can make non-fast-forward pushes on it.
------------
Content-type: text/asciidoc
How to use git-daemon
=====================
Git can be run in inetd mode and in stand alone mode. But all you want is
let a coworker pull from you, and therefore need to set up a git server
......
......@@ -7,8 +7,8 @@ Abstract: Beginning v1.7.9, a contributor can push a signed tag to her
later validate it.
Content-type: text/asciidoc
Using signed tag in pull requests
=================================
How to use a signed tag in pull requests
========================================
A typical distributed workflow using Git is for a contributor to fork a
project, build on it, publish the result to her public repository, and ask
......
GIT index format
================
= The git index file has the following format
== The git index file has the following format
All binary numbers are in network byte order. Version 2 is described
here unless stated otherwise.
......
GIT pack format
===============
= pack-*.pack files have the following format:
== pack-*.pack files have the following format:
- A header appears at the beginning and consists of the following:
......@@ -34,7 +34,7 @@ GIT pack format
- The trailer records 20-byte SHA1 checksum of all of the above.
= Original (version 1) pack-*.idx files have the following format:
== Original (version 1) pack-*.idx files have the following format:
- The header consists of 256 4-byte network byte order
integers. N-th entry of this table records the number of
......@@ -123,8 +123,8 @@ Pack file entry: <+
= Version 2 pack-*.idx files support packs larger than 4 GiB, and
have some other reorganizations. They have the format:
== Version 2 pack-*.idx files support packs larger than 4 GiB, and
have some other reorganizations. They have the format:
- A 4-byte magic number '\377tOc' which is an unreasonable
fanout[0] value.
......
......@@ -117,7 +117,7 @@ A few things to remember here:
- The repository path is always quoted with single quotes.
Fetching Data From a Server
===========================
---------------------------
When one Git repository wants to get data that a second repository
has, the first can 'fetch' from the second. This operation determines
......@@ -134,7 +134,8 @@ with the object name that each reference currently points to.
$ echo -e -n "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" |
nc -v example.com 9418
00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag
00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack
side-band side-band-64k ofs-delta shallow no-progress include-tag
00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration
003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master
003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9
......@@ -421,7 +422,7 @@ entire packfile without multiplexing.
Pushing Data To a Server
========================
------------------------
Pushing data to a server will invoke the 'receive-pack' process on the
server, which will allow the client to tell it which references it should
......
git-send-pack
=============
Git-send-pack internals
=======================
Overall operation
-----------------
......
Def.: Shallow commits do have parents, but not in the shallow
Shallow commits
===============
.Definition
*********************************************************
Shallow commits do have parents, but not in the shallow
repo, and therefore grafts are introduced pretending that
these commits have no parents.
*********************************************************
The basic idea is to write the SHA1s of shallow commits into
$GIT_DIR/shallow, and handle its contents like the contents
......
......@@ -74,24 +74,24 @@ For multiple ancestors, a '+' means that this case applies even if
only one ancestor or remote fits; a '^' means all of the ancestors
must be the same.
case ancest head remote result
----------------------------------------
1 (empty)+ (empty) (empty) (empty)
2ALT (empty)+ *empty* remote remote
2 (empty)^ (empty) remote no merge
3ALT (empty)+ head *empty* head
3 (empty)^ head (empty) no merge
4 (empty)^ head remote no merge
5ALT * head head head
6 ancest+ (empty) (empty) no merge
8 ancest^ (empty) ancest no merge
7 ancest+ (empty) remote no merge
10 ancest^ ancest (empty) no merge
9 ancest+ head (empty) no merge
16 anc1/anc2 anc1 anc2 no merge
13 ancest+ head ancest head
14 ancest+ ancest remote remote
11 ancest+ head remote no merge
case ancest head remote result
----------------------------------------
1 (empty)+ (empty) (empty) (empty)
2ALT (empty)+ *empty* remote remote
2 (empty)^ (empty) remote no merge
3ALT (empty)+ head *empty* head
3 (empty)^ head (empty) no merge
4 (empty)^ head remote no merge
5ALT * head head head
6 ancest+ (empty) (empty) no merge
8 ancest^ (empty) ancest no merge
7 ancest+ (empty) remote no merge
10 ancest^ ancest (empty) no merge
9 ancest+ head (empty) no merge
16 anc1/anc2 anc1 anc2 no merge
13 ancest+ head ancest head
14 ancest+ ancest remote remote
11 ancest+ head remote no merge
Only #2ALT and #3ALT use *empty*, because these are the only cases
where there can be conflicts that didn't exist before. Note that we
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment