From ed7f4f6a711449fd2edb85a26e3e3998586e500d Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 20 May 2007 09:09:09 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.5.2 --- RelNotes-1.5.1.5.txt | 8 +--- RelNotes-1.5.1.6.txt | 45 ++++++++++++++++++ RelNotes-1.5.2.txt | 32 ++++++------- git.html | 2 +- git.txt | 14 ++++-- tutorial-2.html | 4 +- tutorial-2.txt | 3 ++ tutorial.html | 91 +++++++++++++++++++----------------- tutorial.txt | 100 +++++++++++++++++++-------------------- user-manual.html | 95 ++++++++++++++++++++++++++++++++++--- user-manual.txt | 108 ++++++++++++++++++++++++++++++++++++++++++- 11 files changed, 371 insertions(+), 131 deletions(-) create mode 100644 RelNotes-1.5.1.6.txt diff --git a/RelNotes-1.5.1.5.txt b/RelNotes-1.5.1.5.txt index 85e821c43..b0ab8eb37 100644 --- a/RelNotes-1.5.1.5.txt +++ b/RelNotes-1.5.1.5.txt @@ -1,4 +1,4 @@ -GIT v1.5.1.5 Release Notes (draft) +GIT v1.5.1.5 Release Notes ========================== Fixes since v1.5.1.4 @@ -40,9 +40,3 @@ Fixes since v1.5.1.4 compilers on Sun. - Many many documentation fixes and updates. - --- -exec >/var/tmp/1 -O=v1.5.1.4-48-gcecb98a -echo O=`git describe refs/heads/maint` -git shortlog --no-merges $O..refs/heads/maint diff --git a/RelNotes-1.5.1.6.txt b/RelNotes-1.5.1.6.txt new file mode 100644 index 000000000..55f3ac13e --- /dev/null +++ b/RelNotes-1.5.1.6.txt @@ -0,0 +1,45 @@ +GIT v1.5.1.6 Release Notes +========================== + +Fixes since v1.5.1.4 +-------------------- + +* Bugfixes + + - git-send-email did not understand aliases file for mutt, which + allows leading whitespaces. + + - git-format-patch emitted Content-Type and Content-Transfer-Encoding + headers for non ASCII contents, but failed to add MIME-Version. + + - git-name-rev had a buffer overrun with a deep history. + + - contributed script import-tars did not get the directory in + tar archives interpreted correctly. + + - git-svn was reported to segfault for many people on list and + #git; hopefully this has been fixed. + + - git-svn also had a bug to crash svnserve by sending a bad + sequence of requests. + + - "git-svn clone" does not try to minimize the URL + (i.e. connect to higher level hierarchy) by default, as this + can prevent clone to fail if only part of the repository + (e.g. 'trunk') is open to public. + + - "git checkout branch^0" did not detach the head when you are + already on 'branch'; backported the fix from the 'master'. + + - "git-config section.var" did not correctly work when + existing configuration file had both [section] and [section "name"] + next to each other. + + - "git clone ../other-directory" was fooled if the current + directory $PWD points at is a symbolic link. + + - (build) tree_entry_extract() function was both static inline + and extern, which caused trouble compiling with Forte12 + compilers on Sun. + + - Many many documentation fixes and updates. diff --git a/RelNotes-1.5.2.txt b/RelNotes-1.5.2.txt index 7dbdb2698..6195715dc 100644 --- a/RelNotes-1.5.2.txt +++ b/RelNotes-1.5.2.txt @@ -1,18 +1,18 @@ -GIT v1.5.2 Release Notes (draft) +GIT v1.5.2 Release Notes ======================== Updates since v1.5.1 -------------------- -* Plumbing level subproject support. +* Plumbing level superproject support. You can include a subdirectory that has an independent git - repository in your index and tree objects as a - "subproject". This plumbing (i.e. "core") level subproject - support explicitly excludes recursive behaviour. + repository in your index and tree objects of your project + ("superproject"). This plumbing (i.e. "core") level + superproject support explicitly excludes recursive behaviour. - The "subproject" entries in the index and trees are - incompatible with older versions of git. Experimenting with + The "subproject" entries in the index and trees of a superproject + are incompatible with older versions of git. Experimenting with the plumbing level support is encouraged, but be warned that unless everybody in your project updates to this release or later, using this feature would make your project @@ -33,7 +33,8 @@ Updates since v1.5.1 but this feature is an extremely sharp-edged razor and needs to be handled with caution (do not use it unless you understand the earlier mailing list discussion on keyword - expansion). + expansion). These conversions apply when checking files in + or out, and exporting via git-archive. * The packfile format now optionally suports 64-bit index. @@ -42,12 +43,13 @@ Updates since v1.5.1 needs more than 32-bit to express offsets of objects in the pack. -* Comes with an updated git-gui 0.7.0 +* Comes with an updated git-gui 0.7.1 * Updated gitweb: - can show combined diff for merges; - uses font size of user's preference, not hardcoded in pixels; + - can now 'grep'; * New commands and options. @@ -190,12 +192,6 @@ this release, unless otherwise noted. - "git clean -d -X" now does not remove non-excluded directories. -* Documentation updates - -* Performance Tweaks - --- -exec >/var/tmp/1 -O=v1.5.2-rc3 -echo O=`git describe refs/heads/master` -git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint + - rebasing (without -m) a series that changes a symlink to a directory + in the middle of a path confused git-apply greatly and refused to + operate. diff --git a/git.html b/git.html index cb3f9a99a..2eeef129c 100644 --- a/git.html +++ b/git.html @@ -2333,7 +2333,7 @@ contributors on the git-list <git@vger.kernel.org>.

diff --git a/git.txt b/git.txt index 157ef2913..98860af04 100644 --- a/git.txt +++ b/git.txt @@ -41,9 +41,16 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.5.1.5/git.html[documentation for release 1.5.1.5] +* link:v1.5.2/git.html[documentation for release 1.5.2] -* release notes for link:RelNotes-1.5.1.5.txt[1.5.1.5], +* release notes for + link:RelNotes-1.5.2.txt[1.5.2]. + +* link:v1.5.1.6/git.html[documentation for release 1.5.1.6] + +* release notes for + link:RelNotes-1.5.1.6.txt[1.5.1.6], + link:RelNotes-1.5.1.5.txt[1.5.1.5], link:RelNotes-1.5.1.4.txt[1.5.1.4], link:RelNotes-1.5.1.3.txt[1.5.1.3], link:RelNotes-1.5.1.2.txt[1.5.1.2], @@ -52,7 +59,8 @@ Documentation for older releases are available here: * link:v1.5.0.7/git.html[documentation for release 1.5.0.7] -* release notes for link:RelNotes-1.5.0.7.txt[1.5.0.7], +* release notes for + link:RelNotes-1.5.0.7.txt[1.5.0.7], link:RelNotes-1.5.0.6.txt[1.5.0.6], link:RelNotes-1.5.0.5.txt[1.5.0.5], link:RelNotes-1.5.0.3.txt[1.5.0.3], diff --git a/tutorial-2.html b/tutorial-2.html index c6cee87f8..230173330 100644 --- a/tutorial-2.html +++ b/tutorial-2.html @@ -634,6 +634,8 @@ pages for any of the git commands; one good place to start would be with the commands mentioned in Everyday git. You should be able to find any unknown jargon in the Glossary.

+

The Git User's Manual provides a more +comprehensive introduction to git.

The CVS migration document explains how to import a CVS repository into git, and shows how to use git in a CVS-like way.

@@ -645,7 +647,7 @@ example, creating a new commit.

diff --git a/tutorial-2.txt b/tutorial-2.txt index af8d43bd1..5c39a165f 100644 --- a/tutorial-2.txt +++ b/tutorial-2.txt @@ -391,6 +391,9 @@ with the commands mentioned in link:everyday.html[Everyday git]. You should be able to find any unknown jargon in the link:glossary.html[Glossary]. +The link:user-manual.html[Git User's Manual] provides a more +comprehensive introduction to git. + The link:cvs-migration.html[CVS migration] document explains how to import a CVS repository into git, and shows how to use git in a CVS-like way. diff --git a/tutorial.html b/tutorial.html index 52df2bdb3..064de68a2 100644 --- a/tutorial.html +++ b/tutorial.html @@ -265,6 +265,9 @@ div.exampleblock-content {

This tutorial explains how to import a new project into git, make changes to it, and share changes with other developers.

+

If you are instead primarily interested in using git to fetch a project, +for example, to test the latest version, you may prefer to start with +the first two chapters of The Git User's Manual.

First, note that you can get documentation for a command such as "git diff" with:

@@ -297,43 +300,66 @@ $ git init 
Initialized empty Git repository in .git/

You've now initialized the working directory—you may notice a new -directory created, named ".git". Tell git that you want it to track -every file under the current directory (note the .) with:

+directory created, named ".git".

+

Next, tell git to take a snapshot of the contents of all files under the +current directory (note the .), with git-add(1):

$ git add .
-

Finally,

+

This snapshot is now stored in a temporary staging area which git calls +the "index". You can permanently store the contents of the index in the +repository with git-commit(1):

$ git commit
-

will prompt you for a commit message, then record the current state -of all the files to the repository.

+

This will prompt you for a commit message. You've now stored the first +version of your project in git.

Making changes

-

Try modifying some files, then run

+

Modify some files, then add their updated contents to the index:

-
$ git diff
+
$ git add file1 file2 file3
-

to review your changes. When you're done, tell git that you -want the updated contents of these files in the commit and then -make a commit, like this:

+

You are now ready to commit. You can see what is about to be committed +using git-diff(1) with the —cached option:

-
$ git add file1 file2 file3
-$ git commit
+
$ git diff --cached
+
+

(Without —cached, git-diff(1) will show you any changes that +you've made but not yet added to the index.) You can also get a brief +summary of the situation with git-status(1):

+
+
+
$ git status
+# On branch master
+# Changes to be committed:
+#   (use "git reset HEAD <file>..." to unstage)
+#
+#       modified:   file1
+#       modified:   file2
+#       modified:   file3
+#
+
+

If you need to make any further adjustments, do so now, and then add any +newly modified content to the index. Finally, commit your changes with:

+
+
+
$ git commit

This will again prompt your for a message describing the change, and then -record the new versions of the files you listed.

+record a new version of the project.

Alternatively, instead of running git add beforehand, you can use

$ git commit -a
-

which will automatically notice modified (but not new) files.

+

which will automatically notice any modified (but not new) files, add +them to the index, and commit, all in one step.

A note on commit messages: Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more @@ -343,33 +369,12 @@ commit in the body.

Git tracks content not files

-

With git you have to explicitly "add" all the changed _content_ you -want to commit together. This can be done in a few different ways:

-

1) By using git add <file_spec>…

-

This can be performed multiple times before a commit. Note that this -is not only for adding new files. Even modified files must be -added to the set of changes about to be committed. The "git status" -command gives you a summary of what is included so far for the -next commit. When done you should use the git commit command to -make it real.

-

Note: don't forget to add a file again if you modified it after the -first add and before commit. Otherwise only the previous added -state of that file will be committed. This is because git tracks -content, so what you're really adding to the commit is the content -of the file in the state it is in when you add it.

-

2) By using git commit -a directly

-

This is a quick way to automatically add the content from all files -that were modified since the previous commit, and perform the actual -commit without having to separately add them beforehand. This will -not add content from new files i.e. files that were never added before. -Those files still have to be added explicitly before performing a -commit.

-

But here's a twist. If you do git commit <file1> <file2> … then only -the changes belonging to those explicitly specified files will be -committed, entirely bypassing the current "added" changes. Those "added" -changes will still remain available for a subsequent commit though.

-

However, for normal usage you only have to remember git add + git commit -and/or git commit -a.

+

Many revision control systems provide an "add" command that tells the +system to start tracking changes to a new file. Git's "add" command +does something simpler and more powerful: git add is used both for new +and newly modified files, and in both cases it takes a snapshot of the +given files and stages that content in the index, ready for inclusion in +the next commit.

Viewing the changelog

@@ -746,7 +751,7 @@ The index file is a cache of the state of a directory tree,

Part two of this tutorial explains the object database, the index file, and a few other odds and ends that you'll need to make the most of git.

-

If you don't want to consider with that right away, a few other +

If you don't want to continue with that right away, a few other digressions that may be interesting at this point are:

diff --git a/tutorial.txt b/tutorial.txt index 99efce457..f55d4083e 100644 --- a/tutorial.txt +++ b/tutorial.txt @@ -4,6 +4,10 @@ A tutorial introduction to git (for version 1.5.1 or newer) This tutorial explains how to import a new project into git, make changes to it, and share changes with other developers. +If you are instead primarily interested in using git to fetch a project, +for example, to test the latest version, you may prefer to start with +the first two chapters of link:user-manual.html[The Git User's Manual]. + First, note that you can get documentation for a command such as "git diff" with: @@ -40,42 +44,67 @@ Initialized empty Git repository in .git/ ------------------------------------------------ You've now initialized the working directory--you may notice a new -directory created, named ".git". Tell git that you want it to track -every file under the current directory (note the '.') with: +directory created, named ".git". + +Next, tell git to take a snapshot of the contents of all files under the +current directory (note the '.'), with gitlink:git-add[1]: ------------------------------------------------ $ git add . ------------------------------------------------ -Finally, +This snapshot is now stored in a temporary staging area which git calls +the "index". You can permanently store the contents of the index in the +repository with gitlink:git-commit[1]: ------------------------------------------------ $ git commit ------------------------------------------------ -will prompt you for a commit message, then record the current state -of all the files to the repository. +This will prompt you for a commit message. You've now stored the first +version of your project in git. Making changes -------------- -Try modifying some files, then run +Modify some files, then add their updated contents to the index: ------------------------------------------------ -$ git diff +$ git add file1 file2 file3 ------------------------------------------------ -to review your changes. When you're done, tell git that you -want the updated contents of these files in the commit and then -make a commit, like this: +You are now ready to commit. You can see what is about to be committed +using gitlink:git-diff[1] with the --cached option: + +------------------------------------------------ +$ git diff --cached +------------------------------------------------ + +(Without --cached, gitlink:git-diff[1] will show you any changes that +you've made but not yet added to the index.) You can also get a brief +summary of the situation with gitlink:git-status[1]: + +------------------------------------------------ +$ git status +# On branch master +# Changes to be committed: +# (use "git reset HEAD ..." to unstage) +# +# modified: file1 +# modified: file2 +# modified: file3 +# +------------------------------------------------ + +If you need to make any further adjustments, do so now, and then add any +newly modified content to the index. Finally, commit your changes with: ------------------------------------------------ -$ git add file1 file2 file3 $ git commit ------------------------------------------------ This will again prompt your for a message describing the change, and then -record the new versions of the files you listed. +record a new version of the project. Alternatively, instead of running `git add` beforehand, you can use @@ -83,7 +112,8 @@ Alternatively, instead of running `git add` beforehand, you can use $ git commit -a ------------------------------------------------ -which will automatically notice modified (but not new) files. +which will automatically notice any modified (but not new) files, add +them to the index, and commit, all in one step. A note on commit messages: Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) @@ -92,45 +122,15 @@ thorough description. Tools that turn commits into email, for example, use the first line on the Subject: line and the rest of the commit in the body. - Git tracks content not files ---------------------------- -With git you have to explicitly "add" all the changed _content_ you -want to commit together. This can be done in a few different ways: - -1) By using 'git add ...' - -This can be performed multiple times before a commit. Note that this -is not only for adding new files. Even modified files must be -added to the set of changes about to be committed. The "git status" -command gives you a summary of what is included so far for the -next commit. When done you should use the 'git commit' command to -make it real. - -Note: don't forget to 'add' a file again if you modified it after the -first 'add' and before 'commit'. Otherwise only the previous added -state of that file will be committed. This is because git tracks -content, so what you're really 'adding' to the commit is the *content* -of the file in the state it is in when you 'add' it. - -2) By using 'git commit -a' directly - -This is a quick way to automatically 'add' the content from all files -that were modified since the previous commit, and perform the actual -commit without having to separately 'add' them beforehand. This will -not add content from new files i.e. files that were never added before. -Those files still have to be added explicitly before performing a -commit. - -But here's a twist. If you do 'git commit ...' then only -the changes belonging to those explicitly specified files will be -committed, entirely bypassing the current "added" changes. Those "added" -changes will still remain available for a subsequent commit though. - -However, for normal usage you only have to remember 'git add' + 'git commit' -and/or 'git commit -a'. - +Many revision control systems provide an "add" command that tells the +system to start tracking changes to a new file. Git's "add" command +does something simpler and more powerful: `git add` is used both for new +and newly modified files, and in both cases it takes a snapshot of the +given files and stages that content in the index, ready for inclusion in +the next commit. Viewing the changelog --------------------- @@ -564,7 +564,7 @@ link:tutorial-2.html[Part two of this tutorial] explains the object database, the index file, and a few other odds and ends that you'll need to make the most of git. -If you don't want to consider with that right away, a few other +If you don't want to continue with that right away, a few other digressions that may be interesting at this point are: * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert diff --git a/user-manual.html b/user-manual.html index ad1337bf6..395465131 100644 --- a/user-manual.html +++ b/user-manual.html @@ -1,4 +1,4 @@ -Git User's Manual (for version 1.5.1 or newer)

Git User's Manual (for version 1.5.1 or newer)

Table of Contents

Preface
1. Repositories and Branches
How to get a git repository
How to check out a different version of a project
Understanding History: Commits
Understanding history: commits, parents, and reachability
Understanding history: History diagrams
Understanding history: What is a branch?
Manipulating branches
Examining an old version without creating a new branch
Examining branches from a remote repository
Naming branches, tags, and other references
Updating a repository with git fetch
Fetching branches from other repositories
2. Exploring git history
How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
3. Developing with git
Telling git your name
Creating a new repository
How to make a commit
Creating good commit messages
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by editing history
Checking out an old version of a file
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes
4. Sharing development with others
Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Public git repositories
Setting up a public repository
Exporting a git repository via the git protocol
Exporting a git repository via http
Pushing changes to a public repository
Setting up a shared repository
Allowing web browsing of a repository
Examples
Maintaining topic branches for a Linux subsystem maintainer
5. Rewriting history and maintaining patch series
Creating the perfect patch series
Keeping a patch series up to date using git-rebase
Modifying a single commit
Reordering or selecting from a patch series
Other tools
Problems with rewriting history
6. Advanced branch management
Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote branches
7. Git internals
The Object Database
Blob Object
Tree Object
Commit Object
Trust
Tag Object
The "index" aka "Current Directory Cache"
The Workflow
working directory -> index
index -> object database
object database -> index
index -> working directory
Tying it all together
Examining the data
Merging multiple trees
Merging multiple trees, continued
How git stores objects efficiently: pack files
Dangling objects
A birds-eye view of Git's source code
8. GIT Glossary
A. Git Quick Start
Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance
B. Notes and todo list for this manual

Preface

Git is a fast distributed revision control system.

This manual is designed to be readable by someone with basic unix +Git User's Manual (for version 1.5.1 or newer)

Git User's Manual (for version 1.5.1 or newer)

Table of Contents

Preface
1. Repositories and Branches
How to get a git repository
How to check out a different version of a project
Understanding History: Commits
Understanding history: commits, parents, and reachability
Understanding history: History diagrams
Understanding history: What is a branch?
Manipulating branches
Examining an old version without creating a new branch
Examining branches from a remote repository
Naming branches, tags, and other references
Updating a repository with git fetch
Fetching branches from other repositories
2. Exploring git history
How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
Finding commits referencing a file with given content
3. Developing with git
Telling git your name
Creating a new repository
How to make a commit
Creating good commit messages
Ignoring files
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by editing history
Checking out an old version of a file
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes
4. Sharing development with others
Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Public git repositories
Setting up a public repository
Exporting a git repository via the git protocol
Exporting a git repository via http
Pushing changes to a public repository
Setting up a shared repository
Allowing web browsing of a repository
Examples
Maintaining topic branches for a Linux subsystem maintainer
5. Rewriting history and maintaining patch series
Creating the perfect patch series
Keeping a patch series up to date using git-rebase
Modifying a single commit
Reordering or selecting from a patch series
Other tools
Problems with rewriting history
6. Advanced branch management
Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote branches
7. Git internals
The Object Database
Blob Object
Tree Object
Commit Object
Trust
Tag Object
The "index" aka "Current Directory Cache"
The Workflow
working directory -> index
index -> object database
object database -> index
index -> working directory
Tying it all together
Examining the data
Merging multiple trees
Merging multiple trees, continued
How git stores objects efficiently: pack files
Dangling objects
A birds-eye view of Git's source code
8. GIT Glossary
A. Git Quick Start
Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance
B. Notes and todo list for this manual

Preface

Git is a fast distributed revision control system.

This manual is designed to be readable by someone with basic unix command-line skills, but no previous knowledge of git.

Chapter 1, Repositories and Branches and Chapter 2, Exploring git history explain how to fetch and study a project using git—read these chapters to learn how to build and test a particular version of a software project, search for @@ -224,7 +224,7 @@ a new stanza:

$ ...

This is what causes git to track the remote's branches; you may modify or delete these configuration options by editing .git/config with a text editor. (See the "CONFIGURATION FILE" section of -git-config(1) for details.)

Chapter 2. Exploring git history

Table of Contents

How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release

Git is best thought of as a tool for storing the history of a +git-config(1) for details.)

Chapter 2. Exploring git history

Table of Contents

How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
Finding commits referencing a file with given content

Git is best thought of as a tool for storing the history of a collection of files. It does this by storing compressed snapshots of the contents of a file heirarchy, together with "commits" which show the relationships between these snapshots.

Git provides extremely flexible and fast tools for exploring the @@ -385,7 +385,12 @@ echo echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new"
echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"
echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"

and then he just cut-and-pastes the output commands after verifying that -they look OK.

Chapter 3. Developing with git

Table of Contents

Telling git your name
Creating a new repository
How to make a commit
Creating good commit messages
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by editing history
Checking out an old version of a file
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes

Telling git your name

Before creating any commits, you should introduce yourself to git. The +they look OK.

Finding commits referencing a file with given content

Somebody hands you a copy of a file, and asks which commits modified a +file such that it contained the given content either before or after the +commit. You can find out with this:

$  git log --raw -r --abbrev=40 --pretty=oneline -- filename |
+        grep -B 1 `git hash-object filename`

Figuring out why this works is left as an exercise to the (advanced) +student. The git-log(1), git-diff-tree(1), and +git-hash-object(1) man pages may prove helpful.

Chapter 3. Developing with git

Table of Contents

Telling git your name
Creating a new repository
How to make a commit
Creating good commit messages
Ignoring files
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by editing history
Checking out an old version of a file
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes

Telling git your name

Before creating any commits, you should introduce yourself to git. The easiest way to do so is to make sure the following lines appear in a file named .gitconfig in your home directory:

[user]
        name = Your Name Comes Here
@@ -428,7 +433,64 @@ with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. Tools that turn commits into email, for example, use the first line on the Subject line and the rest of the commit in the -body.

How to merge

You can rejoin two diverging branches of development using +body.

Ignoring files

A project will often generate files that you do not want to track with git. +This typically includes files generated by a build process or temporary +backup files made by your editor. Of course, not tracking files with git +is just a matter of not calling "git add" on them. But it quickly becomes +annoying to have these untracked files lying around; e.g. they make +"git add ." and "git commit -a" practically useless, and they keep +showing up in the output of "git status", etc.

Git therefore provides "exclude patterns" for telling git which files to +actively ignore. Exclude patterns are thoroughly explained in the +"Exclude Patterns" section of the git-ls-files(1) manual page, +but the heart of the concept is simply a list of files which git should +ignore. Entries in the list may contain globs to specify multiple files, +or may be prefixed by "!" to explicitly include (un-ignore) a previously +excluded (ignored) file (i.e. later exclude patterns override earlier ones). +The following example should illustrate such patterns:

# Lines starting with '#' are considered comments.
+# Ignore foo.txt.
+foo.txt
+# Ignore (generated) html files,
+*.html
+# except foo.html which is maintained by hand.
+!foo.html
+# Ignore objects and archives.
+*.[oa]

The next question is where to put these exclude patterns so that git can +find them. Git looks for exclude patterns in the following files:

+.gitignore files in your working tree: +
+ You may store multiple .gitignore files at various locations in your + working tree. Each .gitignore file is applied to the directory where + it's located, including its subdirectories. Furthermore, the + .gitignore files can be tracked like any other files in your working + tree; just do a "git add .gitignore" and commit. .gitignore is + therefore the right place to put exclude patterns that are meant to + be shared between all project participants, such as build output files + (e.g. *.o), etc. +
+.git/info/exclude in your repo: +
+ Exclude patterns in this file are applied to the working tree as a + whole. Since the file is not located in your working tree, it does + not follow push/pull/clone like .gitignore can do. This is therefore + the place to put exclude patterns that are local to your copy of the + repo (i.e. not shared between project participants), such as + temporary backup files made by your editor (e.g. *~), etc. +
+The file specified by the core.excludesfile config directive: +
+ By setting the core.excludesfile config directive you can tell git + where to find more exclude patterns (see git-config(1) for + more information on configuration options). This config directive + can be set in the per-repo .git/config file, in which case the + exclude patterns will apply to that repo only. Alternatively, you + can set the directive in the global ~/.gitconfig file to apply + the exclude pattern to all your git repos. As with the above + .git/info/exclude (and, indeed, with git config directives in + general), this directive does not follow push/pull/clone, but remain + local to your repo(s). +

Note

In addition to the above alternatives, there are git commands that can take +exclude patterns directly on the command line. See git-ls-files(1) +for an example of this.

How to merge

You can rejoin two diverging branches of development using git-merge(1):

$ git merge branchname

merges the development in the branch "branchname" into the current branch. If there are conflicts—for example, if the same file is modified in two different ways in the remote branch and the local @@ -717,7 +779,28 @@ details.

git for CVS users for instructions on how to -set this up.

Allowing web browsing of a repository

The gitweb cgi script provides users an easy way to browse your +set this up.

However, while there is nothing wrong with git's support for shared +repositories, this mode of operation is not generally recommended, +simply because the mode of collaboration that git supports—by +exchanging patches and pulling from public repositories—has so many +advantages over the central shared repository:

  • +Git's ability to quickly import and merge patches allows a + single maintainer to process incoming changes even at very + high rates. And when that becomes too much, git-pull provides + an easy way for that maintainer to delegate this job to other + maintainers while still allowing optional review of incoming + changes. +
  • +Since every developer's repository has the same complete copy + of the project history, no repository is special, and it is + trivial for another developer to take over maintenance of a + project, either by mutual agreement, or because a maintainer + becomes unresponsive or difficult to work with. +
  • +The lack of a central group of "committers" means there is + less need for formal decisions about who is "in" and who is + "out". +

Allowing web browsing of a repository

The gitweb cgi script provides users an easy way to browse your project's files and history without having to install git; see the file gitweb/INSTALL in the git source tree for instructions on setting it up.

Examples

Maintaining topic branches for a Linux subsystem maintainer

This describes how Tony Luck uses git in his role as maintainer of the IA64 architecture for the Linux kernel.

He uses two public branches:

  • @@ -2069,7 +2152,7 @@ $ no more knowledge than necessary: for example, "importing patches into a project" rather than "the git-am command"

    Think about how to create a clear chapter dependency graph that will allow people to get to important topics without necessarily reading -everything in between.

    Say something about .gitignore.

    Scan Documentation/ for other stuff left out; in particular: +everything in between.

    Scan Documentation/ for other stuff left out; in particular: howto's some of technical/? hooks diff --git a/user-manual.txt b/user-manual.txt index c4bff474d..52247aa71 100644 --- a/user-manual.txt +++ b/user-manual.txt @@ -921,6 +921,22 @@ echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new" and then he just cut-and-pastes the output commands after verifying that they look OK. +Finding commits referencing a file with given content +----------------------------------------------------- + +Somebody hands you a copy of a file, and asks which commits modified a +file such that it contained the given content either before or after the +commit. You can find out with this: + +------------------------------------------------- +$ git log --raw -r --abbrev=40 --pretty=oneline -- filename | + grep -B 1 `git hash-object filename` +------------------------------------------------- + +Figuring out why this works is left as an exercise to the (advanced) +student. The gitlink:git-log[1], gitlink:git-diff-tree[1], and +gitlink:git-hash-object[1] man pages may prove helpful. + [[Developing-with-git]] Developing with git =================== @@ -1073,6 +1089,75 @@ description. Tools that turn commits into email, for example, use the first line on the Subject line and the rest of the commit in the body. +[[ignoring-files]] +Ignoring files +-------------- + +A project will often generate files that you do 'not' want to track with git. +This typically includes files generated by a build process or temporary +backup files made by your editor. Of course, 'not' tracking files with git +is just a matter of 'not' calling "`git add`" on them. But it quickly becomes +annoying to have these untracked files lying around; e.g. they make +"`git add .`" and "`git commit -a`" practically useless, and they keep +showing up in the output of "`git status`", etc. + +Git therefore provides "exclude patterns" for telling git which files to +actively ignore. Exclude patterns are thoroughly explained in the +"Exclude Patterns" section of the gitlink:git-ls-files[1] manual page, +but the heart of the concept is simply a list of files which git should +ignore. Entries in the list may contain globs to specify multiple files, +or may be prefixed by "`!`" to explicitly include (un-ignore) a previously +excluded (ignored) file (i.e. later exclude patterns override earlier ones). +The following example should illustrate such patterns: + +------------------------------------------------- +# Lines starting with '#' are considered comments. +# Ignore foo.txt. +foo.txt +# Ignore (generated) html files, +*.html +# except foo.html which is maintained by hand. +!foo.html +# Ignore objects and archives. +*.[oa] +------------------------------------------------- + +The next question is where to put these exclude patterns so that git can +find them. Git looks for exclude patterns in the following files: + +`.gitignore` files in your working tree::: + You may store multiple `.gitignore` files at various locations in your + working tree. Each `.gitignore` file is applied to the directory where + it's located, including its subdirectories. Furthermore, the + `.gitignore` files can be tracked like any other files in your working + tree; just do a "`git add .gitignore`" and commit. `.gitignore` is + therefore the right place to put exclude patterns that are meant to + be shared between all project participants, such as build output files + (e.g. `\*.o`), etc. +`.git/info/exclude` in your repo::: + Exclude patterns in this file are applied to the working tree as a + whole. Since the file is not located in your working tree, it does + not follow push/pull/clone like `.gitignore` can do. This is therefore + the place to put exclude patterns that are local to your copy of the + repo (i.e. 'not' shared between project participants), such as + temporary backup files made by your editor (e.g. `\*~`), etc. +The file specified by the `core.excludesfile` config directive::: + By setting the `core.excludesfile` config directive you can tell git + where to find more exclude patterns (see gitlink:git-config[1] for + more information on configuration options). This config directive + can be set in the per-repo `.git/config` file, in which case the + exclude patterns will apply to that repo only. Alternatively, you + can set the directive in the global `~/.gitconfig` file to apply + the exclude pattern to all your git repos. As with the above + `.git/info/exclude` (and, indeed, with git config directives in + general), this directive does not follow push/pull/clone, but remain + local to your repo(s). + +[NOTE] +In addition to the above alternatives, there are git commands that can take +exclude patterns directly on the command line. See gitlink:git-ls-files[1] +for an example of this. + [[how-to-merge]] How to merge ------------ @@ -1857,6 +1942,27 @@ all push to and pull from a single shared repository. See link:cvs-migration.html[git for CVS users] for instructions on how to set this up. +However, while there is nothing wrong with git's support for shared +repositories, this mode of operation is not generally recommended, +simply because the mode of collaboration that git supports--by +exchanging patches and pulling from public repositories--has so many +advantages over the central shared repository: + + - Git's ability to quickly import and merge patches allows a + single maintainer to process incoming changes even at very + high rates. And when that becomes too much, git-pull provides + an easy way for that maintainer to delegate this job to other + maintainers while still allowing optional review of incoming + changes. + - Since every developer's repository has the same complete copy + of the project history, no repository is special, and it is + trivial for another developer to take over maintenance of a + project, either by mutual agreement, or because a maintainer + becomes unresponsive or difficult to work with. + - The lack of a central group of "committers" means there is + less need for formal decisions about who is "in" and who is + "out". + [[setting-up-gitweb]] Allowing web browsing of a repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3816,8 +3922,6 @@ Think about how to create a clear chapter dependency graph that will allow people to get to important topics without necessarily reading everything in between. -Say something about .gitignore. - Scan Documentation/ for other stuff left out; in particular: howto's some of technical/? -- 2.26.2