Rewrite the introduction. Rewrite each section completely to make them
work in the new order, to add some examples, and to move plumbing
commands (like git-commit-tree) to the following chapter.
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
The bottom-up blog, tree, commit order makes sense unless you want to
give explicit examples--it's easier to discover objects to examine if
you go in the other order....,
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
Add an example using git-ls-files, standardize on the new "index"
terminology (as opposed to "cache"), attempt to clarify discussion and
make it a little shorter, avoid some unnecessary jargon ("write-back
cache").
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
The low-level index operations aren't as important to regular users as
the rest of this "git concepts" chapter; so move it into a separate
chapter, and do some minor cleanup.
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
"git internals" sounds like something only git developers must know
about, but this stuff should be of wider interest. Rename the chapter
and give it a slightly friendlier introduction.
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
The descriptions of the various object types should all be a subsection
of the "Object Database" section.
I cribbed most of this chapter from the README (now core-intro.txt and
git(7)), because there's stuff in there people need to know and I was
too lazy to rewrite it. The audience isn't quite right, though--the
chapter is a mixture of user- and developer- level documentation that
isn't as appropriate now as it was originally.
So, reserve this chapter for stuff users need to know, and move the
source code introduction into a new "git hacking" chapter where we'll
also move any hacker-only technical details.
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
Actually, we should have a competition for the favorite example commit.
Criteria:
- length: one-line changes with one-line comments preferred,
and no long lines
- significance/memorability
- comic value
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
The immediate motivation for writing this section was to explain the
various places ignore patterns could be used. However, I still think
.gitignore is the case most people will want to learn about first. It
also makes it a bit more concrete to introduce ignore patterns in the
context of .gitignore first. And the existance of gitignore(5) relieves
the pressure to explain it all here.
So, stick to the .gitignore example, with only a brief mention of the
others, explain the syntax only by example, and leave the rest to
gitignore(5).
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
Cc: Johan Herland <johan@herland.net>
The git gui project seems to be still in early stages, but at a point
where it's worth mentioning as an alternative way of creating commits.
One feature of interest is the ability to manipulate individual diff
hunks. However, people have found that feature not to be easily
discoverable from the user-interface. Pending some ui improvements, a
parenthetical hint here may help.
(Thanks to Steffen Prohask and Junio Hamano for suggesting the
language.)
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
Update documentation to reflect the --track default.
That change seems to have happened in the 1.5.3 -rc's, so bump the "for
version x.y.z or newer" warning as well.
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
* maint:
user-manual: fix directory name in git-archive example
user-manual: more explanation of push and pull usage
tutorial: Fix typo
user-manual: grammar and style fixes
Recently a user on the mailing list complained that they'd read the
manual but couldn't figure out how to keep a couple private repositories
in sync. They'd tried using push, and were surprised by the effect.
Add a little text in an attempt to make it clear that:
- Pushing to a branch that is checked out will have odd results.
- It's OK to synchronize just using pull if that's simpler.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
- "method of" is vulgar, "method for" is nicer
- "recovery" becomes "recovering" from Steve Hoelzer's original version
of this patch
- "if you want" is nicer as "if you wish"
- "you may" should be "you can"; "you may" is "you have permission to"
rather than "you can"'s "it is possible to"
Signed-off-by: Andy Parkins <andyparkins@gmail.com>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
This one fixes a small formulation weirdness in
Documentation/user-manual.txt
Signed-off-by: Marcus Fritzsch <m@fritschy.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It turns out that the attribute definition we have had for a
long time to hide "^" character from AsciiDoc 7 was not honored
by AsciiDoc 8 even under "-a asciidoc7compatible" mode. There is
a similar breakage with the "compatible" mode with + characters.
The double colon at the end of definition list term needs
to be attached to the term, without a whitespace. After this
minimum fixups, AsciiDoc 8 (I used 8.2.1 on Debian) with
compatibility mode seems to produce reasonably good results.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* maint:
tutorial: use "project history" instead of "changelog" in header
Documentation: user-manual todo
user-manual: add a missing section ID
Fix typo in remote branch example in git user manual
user-manual: quick-start updates
In Documentation/user-manual.txt the example
$ git checkout --track -b origin/maint maint
under "Getting updates with git pull", should read
$ git checkout --track -b maint origin/maint
This was noticed by Ron, and reported through
http://bugs.debian.org/427502
Signed-off-by: Gerrit Pape <pape@smarden.org>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Update text to reflect new position in appendix.
Update the name to reflect the fact that this is closer to reference
than tutorial documentation (as suggested by Jonas Fonseca).
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
This uses "git-apply --whitespace=strip" to fix whitespace errors that have
crept in to our source files over time. There are a few files that need
to have trailing whitespaces (most notably, test vectors). The results
still passes the test, and build result in Documentation/ area is unchanged.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Only git-ls-files(1) describes the gitignore format in detail, and it does so
with reference to git-ls-files options. Most users don't use the plumbing
command git-ls-files directly, and shouldn't have to look in its manpage for
information on the gitignore format.
Create a new manpage gitignore(5) (Documentation/gitignore.txt), and factor
out the gitignore documentation into that file, changing it to refer to
.gitignore and $GIT_DIR/info/exclude as used by porcelain commands. Reference
gitignore(5) from other relevant manpages and documentation. Remove
now-redundant information on exclude patterns from git-ls-files(1), leaving
only information on how git-ls-files options specify exclude patterns and what
precedence they have.
Signed-off-by: Josh Triplett <josh@freedesktop.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
The todo list at the end of the user manual says that something must be
said about .gitignore. Also, there seems to be a lack of documentation
on how to choose between the various types of ignore files (.gitignore
vs. .git/info/exclude, etc.).
This patch adds a section on ignoring files which try to introduce how
to tell git about ignored files, and how the different strategies
complement eachother.
The syntax of exclude patterns is explained in a simplified manner, with
a reference to git-ls-files(1) which already contains a more thorough
explanation.
Signed-off-by: Johan Herland <johan@herland.net>
Another amusing git exploration example brought up in irc. (Credit to
aeruder for the complete solution.)
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
I don't really want to look like we're encouraging the shared repository
thing. Take down some of the argument for using purely
single-developer-owned repositories and collaborating using patches and
pulls instead.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Helping a couple people set up public repos recently, I wanted to point
them at this piece of the user manual, but found it wasn't as helpful as
it could be:
- It starts with a big explanation of why you'd want a public
repository, not necessary in their case since they already knew
why they wanted that. So, separate that out.
- It skimps on some of the git-daemon details, and puts the http
export information first. Fix that.
Also group all the public repo subsections into a single section, and do
some miscellaneous related editing.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Move howto/using-topic-branches into the user manual as an example for
the "sharing development" chapter. While we're at it, remove some
discussion that's covered in earlier chapters, modernize somewhat (use
separate-heads setup, remotes, replace "whatchanged" by "log", etc.),
and replace syntax we'd need to explain by syntax we've already covered
(e.g. old..new instead of new ^old).
The result may not really describe what Tony Luck does any more.... Hope
that's not annoying.
Cc: Tony Luck <tony.luck@intel.com>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
There seems to be a perception that the howto's are bit-rotting a
little. The manual might be a more visible location for some of them,
and make-dist.txt seems like a good candidate to include as an example
in the manual.
For now, incorporate much of it verbatim. Later we may want to update
the example a bit.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
The quick start interrupts the flow of the manual a bit. Move it to
"appendix A" but add a reference to it in the preface. Also rename the
todo chapter to "appendix B", and revise the preface a little.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Some revisions suggested by Junio along with some minor style fixes and
one compile fix (asterisks need escaping).
Cc: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
In http://thread.gmane.org/gmane.comp.version-control.git/42479,
a birdview on the source code was requested.
J. Bruce Fields suggested that my reply should be included in the
user manual, and there was nothing of an outcry, so here it is,
not 2 months later.
It includes modifications as suggested by J. Bruce Fields, Karl
Hasselström and Daniel Barkalow.
Signed-off-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>
* maint:
format-patch: add MIME-Version header when we add content-type.
Fixed link in user-manual
import-tars: Use the "Link indicator" to identify directories
git name-rev writes beyond the end of malloc() with large generations
Documentation/branch: fix small typo in -D example
Currently
$ git grep '\([^t]\|^\)'link: user-manual.txt
gives four hits that refer to .txt version of the documentation
set, but at least "hooks" and "cvs-migration" have HTML variants
installed, so refer to them instead.
Signed-off-by: Junio C Hamano <junkio@cox.net>
More typo fixes from Santi Béjar, plus a couple other mistakes I noticed
along the way.
Cc: Santi Béjar <sbejar@gmail.com>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
I cherry-picked some additional miscellaneous fixes from those suggested
by Santi Béjar, including fixes to:
- correct discussion of repository/HEAD->repository shortcut
- add mention of git-mergetool
- add mention of --track
- mention "-f" as well as "+" for fetch
Cc: Santi Béjar <sbejar@gmail.com>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Santi Béjar points out that when telling people how to "introduce
themselves" to git we're advising them to replace their entire
.gitconfig file. Fix that.
Cc: "Santi Béjar <sbejar@gmail.com>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
The previous commit calls attention to the fact that we have two
sections each devoted to fast-forwards and to dangling objects. Revise
and attempt to differentiate them a bit. Some more reorganization may
be required later....
Signed-off-by: J. Bruce Fields
Any section lacking an id gets an annoying warning when you build
the manual. More seriously, the table of contents then generates
volatile id's which change with every build, with the effect that
we get URL's that change all the time.
The ID's are manually generated and sometimes inconsistent, but
that's OK.
XXX: what to do about the preface?
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Nicolas Pitre pointed out a couple typos and some room for improvement
in the discussion of detached heads.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Cc: Nicolas Pitre <nico@cam.org>
Most other documentation will frequently be read from an installation
of git so will naturally be associated with the installed version.
But these two documents in particular are often read from web pages
while users are still exploring git. It's important to mention
version 1.5.1 since these documents provide example commands that
won't work with previous versions of git.
Signed-off-by: Junio C Hamano <junkio@cox.net>
This is slightly simpler if we use a detached head. And it's probably
good to have another example that uses this feature.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
Add a brief mention of detached HEADs and .git/HEAD.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
The name "master" isn't actually quite so special. Also, fix some bad
grammar.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
Mainly consistent usage of "git command" and not "git-command" syntax
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
Acked-by: J. Bruce Fields <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
* maint:
user-manual: introduce "branch" and "branch head" differently
glossary: clean up cross-references
glossary: stop generating automatically
user-manual: Use def_ instead of ref_ for glossary references.
user-manual.txt: fix a tiny typo.
user-manual: run xsltproc without --nonet option
I was using "branch" to mean "head", but that's perhaps a little
sloppy; so instead start by using the terms "branch head" and "head",
while still quickly falling back on "branch", since that's what
people actually say more frequently.
Also include glossary references on the first uses of "head" and "tag".
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
The sort_glossary.pl script sorts the glossary, checks for duplicates,
and automatically adds cross-references.
But it's not so hard to do all that by hand, and sometimes the automatic
cross-references are a little wrong; so let's run the script one last
time and check in its output.
Note: to make the output fit better into the user manual I also deleted
the acknowledgements at the end, which was maybe a little rude; feel
free to object and I can find a different solution.
Cc: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
"file patch" was doubtless intended to be "file path",
but "directory name" is clearer.
Signed-off-by: Jim Meyering <jim@meyering.net>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
* maint:
git.el: Retrieve commit log information from .dotest directory.
git.el: Avoid appending a signoff line that is already present.
setup_git_directory_gently: fix off-by-one error
user-manual: install user manual stylesheet with other web documents
user-manual: fix rendering of history diagrams
user-manual: fix missing colon in git-show example
user-manual: fix inconsistent use of pull and merge
user-manual: fix inconsistent example
glossary: fix overoptimistic automatic linking of defined terms
Documentation: s/seperator/separator/
Adjust reflog filemode in shared repository
Asciidoc appears to interpret a backslash at the end of a line as
escaping the end-of-line character, which screws up the display of
history diagrams like
o--o--o
\
o--...
The obvious fix (replacing "\" by "\\") doesn't work. The only
workaround I've found is to include all such diagrams in a LiteralBlock.
Asciidoc claims that should be equivalent to a literal paragraph, so I
don't understand why the difference--perhaps it's an asciidoc bug.
Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
There should be a colon in this git-show example.
Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
I used "git pull ." instead of "git merge" here without any explanation.
Stick instead to "git merge" for now (the equivalent pull syntax is
still covered in a later chapter).
Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
The configuration file fragment here is inconsistent with the text
above. Thanks to Ramsay Jones for the correction.
Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
* maint:
GIT 1.5.0.3
glossary: Add definitions for dangling and unreachable objects
user-manual: more detailed merge discussion
user-manual: how to replace commits older than most recent
user-manual: insert earlier of mention content-addressable architecture
user-manual: ensure generated manual references stylesheet
user-manual: reset to ORIG_HEAD not HEAD to undo merge
Documentation: mention module option to git-cvsimport
Add more details on conflict, including brief discussion of file stages.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
"Modifying" an old commit by checking it out, --amend'ing it, then
rebasing on top of it, is a slightly cumbersome technique, but I've
found it useful frequently enough to make it seem worth documenting.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
The content-addressable design is too important not to be worth at least
a brief mention a little earlier on.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
As Linus pointed out recently on the mailing list,
git reset --hard HEAD^
doesn't undo a merge in the case where the merge did a fast-forward. So
the rcommendation here is a little dangerous.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
* maint:
builtin-fmt-merge-msg: fix bugs in --file option
index-pack: Loop over pread until data loading is complete.
blameview: Fix the browse behavior in blameview
Fix minor typos/grammar in user-manual.txt
Correct ordering in git-cvsimport's option documentation
git-show: Reject native ref
Fix git-show man page formatting in the EXAMPLES section
I'd like complete gitweb setup instructions some day, but for now just
refer to the gitweb README.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Document Junio's show-branch trick for finding out which tags are
descendents of a given comit.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
I still really want a section on interoperability with CVS, subversion,
etc., but I'm not getting around to it very fast, so just add this to
the TODO section for now. And a few other minor todo updates.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Add a brief discussion of reflogs. Also recovery of dangling commits
seems to fit in here, so move some of the discussion out of Linus's
email to here.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Direct editing of config files may be more natural for users than using
the git-config commandline; but we should still reference the
git-config man page when we describe such editing, so people know where
to go for details on the config file syntax and meanings of the
variables.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Looks like we're going to allow git-config as the preferred alias to
git-repo-config, so let's document that instead.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Initial import of fsck and dangling objects discussion, mostly lifted from
an email from Linus.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Keep git remote discussion in the first chapter, but postpone
lower-level git fetch usage (to fetch individual branches) till later.
Import a bunch of slightly modified text from the readme to give an
architectural overview at the end.
Add more discussion of history rewriting.
And a bunch of other miscellaneous changes....
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
It appears git-gc will no longer prune automatically, so we don't
need to tell people not to do other stuff while running it.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Since references may be packed, it's no longer as helpful to
introduce references as paths relative to .git.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Correct command line examples of repo-config, format-patch and am.
A full object name is 40-hexdigit; it may be 20-byte but
20-digit is misleading.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Add discussion of git-rebase, patch series, history rewriting.
Mention "pull ." as a synonym for "merge".
Remind myself of another case I want to cover in the other-vcs's chapter.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Add a brief description of the organization to the preface, expand the
final notes/todo's section, in hopes maybe some others will want to
contribute.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
The goals are:
- Readable from beginning to end in order without having read
any other git documentation beforehand.
- Helpful section names and cross-references, so it's not too
hard to skip around some if you need to.
- Organized to allow it to grow much larger (unlike the
tutorials)
It's more liesurely than tutorial.txt, but tries to stay focused on
practical how-to stuff. It adds a discussion of how to resolve merge
conflicts, and partial instructions on setting up and dealing with a
public repository.
I've lifted a little bit from "branching and merging" (e.g., some of the
discussion of history diagrams), and could probably steal more if that's
OK. (Similarly anyone should of course feel free to reuse bits of this
if any parts seem more useful than the whole.)
There's a lot of detail on managing branches and using git-fetch, just
because those are essential even to people needing read-only access
(e.g., kernel testers). I think those sections will be much shorter
once the new "git remote" command and the disconnected checkouts are
taken into account.
I do feel bad about adding yet another piece of documentation, but I we
need something that goes through all the basics in a logical order, and
I wasn't seeing how to grow the tutorials into that.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
