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

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 @@ -390,7 +390,7 @@ 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 +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
Temporarily setting aside work in progress

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 +428,10 @@ $Â gitÂ diffÂ Â Â Â Â Â Â Â Â Â #Â differenceÂ betweenÂ theÂ indexÂ fileÂ andÂ y Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â #Â beÂ includedÂ ifÂ youÂ ranÂ "commit"Â now.
$Â gitÂ diffÂ HEADÂ Â Â Â Â #Â differenceÂ betweenÂ HEADÂ andÂ workingÂ tree;Â what
Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â #Â wouldÂ beÂ committedÂ ifÂ youÂ ranÂ "commitÂ -a"Â now.
-$Â gitÂ statusÂ Â Â Â Â Â Â Â #Â aÂ briefÂ per-fileÂ summaryÂ ofÂ theÂ above.

Creating good commit messages

Though not required, it's a good idea to begin the commit message +$Â gitÂ statusÂ Â Â Â Â Â Â Â #Â aÂ briefÂ per-fileÂ summaryÂ ofÂ theÂ above.

You can also use git-gui(1) to create commits, view changes in +the index and the working tree files, and individually select diff hunks +for inclusion in the index (by right-clicking on the diff hunk and +choosing "Stage Hunk For Commit").

Creating good 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 thorough description. Tools that turn commits into email, for example, use @@ -615,7 +618,16 @@ branches, but it has quite different behavior if it is given a path name: the command

$Â gitÂ checkoutÂ HEAD^Â path/to/file

replaces path/to/file by the contents it had in the commit HEAD^, and also updates the index to match. It does not change branches.

If you just want to look at an old version of the file, without modifying the working directory, you can do that with -git-show(1):

$Â gitÂ showÂ HEAD^:path/to/file

which will display the given version of the file.

Ensuring good performance

On large repositories, git depends on compression to keep the history +git-show(1):

$Â gitÂ showÂ HEAD^:path/to/file

which will display the given version of the file.

Temporarily setting aside work in progress

While you are in the middle of working on something complicated, you +find an unrelated but obvious and trivial bug. You would like to fix it +before continuing. You can use git-stash(1) to save the current +state of your work, and after fixing the bug (or, optionally after doing +so on a different branch and then coming back), unstash the +work-in-progress changes.

$Â gitÂ stashÂ "workÂ inÂ progressÂ forÂ fooÂ feature"

This command will save your changes away to the stash, and +reset your working tree and the index to match the tip of your +current branch. Then you can make your fix as usual.

...Â editÂ andÂ testÂ ...
+$Â gitÂ commitÂ -aÂ -mÂ "blorpl:Â typofix"

After that, you can go back to what you were working on with +git stash apply:

$Â gitÂ stashÂ apply

Ensuring reliability

Checking the repository for corruption

The git-fsck(1) command runs a number of self-consistency checks @@ -677,14 +689,13 @@ into your own work.

We have already seen

$Â gitÂ fetch
$Â gitÂ mergeÂ origin/master

However, the git-pull(1) command provides a way to do this in -one step:

$Â gitÂ pullÂ originÂ master

In fact, "origin" is normally the default repository to pull from, -and the default branch is normally the HEAD of the remote repository, -so often you can accomplish the above with just

$Â gitÂ pull

See the descriptions of the branch.<name>.remote and branch.<name>.merge -options in git-config(1) to learn how to control these defaults -depending on the current branch. Also note that the âtrack option to -git-branch(1) and git-checkout(1) can be used to -automatically set the default remote branch to pull from at the time -that a branch is created:

$Â gitÂ checkoutÂ --trackÂ -bÂ maintÂ origin/maint

In addition to saving you keystrokes, "git pull" also helps you by +one step:

$Â gitÂ pullÂ originÂ master

In fact, if you have "master" checked out, then by default "git pull" +merges from the HEAD branch of the origin repository. So often you can +accomplish the above with just a simple

$Â gitÂ pull

More generally, a branch that is created from a remote branch will pull +by default from that branch. See the descriptions of the +branch.<name>.remote and branch.<name>.merge options in +git-config(1), and the discussion of the âtrack option in +git-checkout(1), to learn how to control these defaults.

In addition to saving you keystrokes, "git pull" also helps you by producing a default commit message documenting the branch and repository that you pulled from.

(But note that no such commit will be created in the case of a fast forward; instead, your branch will just be @@ -1029,8 +1040,10 @@ new commit that records it. So, for example, if "mywork" points to a series of patches on top of "origin", you might do something like:

$Â gitÂ checkoutÂ -bÂ mywork-newÂ origin
$Â gitkÂ origin..myworkÂ &

And browse through the list of patches in the mywork branch using gitk, applying them (possibly in a different order) to mywork-new using -cherry-pick, and possibly modifying them as you go using commit -âamend.

Another technique is to use git-format-patch to create a series of +cherry-pick, and possibly modifying them as you go using commit âamend. +The git-gui[1] command may also help as it allows you to individually +select diff hunks for inclusion in the index (by right-clicking on the +diff hunk and choosing "Stage Hunk for Commit").

Another technique is to use git-format-patch to create a series of patches, then reset the state to before the patches:

$Â gitÂ format-patchÂ origin
$Â gitÂ resetÂ --hardÂ origin

Then modify, reorder, or eliminate patches as preferred before applying them again with git-am(1).

Other tools

There are numerous other tools, such as stgit, which exist for the diff --git a/user-manual.txt b/user-manual.txt index 0071cd070..f89952ad8 100644 --- a/user-manual.txt +++ b/user-manual.txt @@ -1,4 +1,4 @@ -Git User's Manual (for version 1.5.1 or newer) +Git User's Manual (for version 1.5.3 or newer) ______________________________________________ @@ -1079,6 +1079,11 @@ $ git diff HEAD # difference between HEAD and working tree; what $ git status # a brief per-file summary of the above. ------------------------------------------------- +You can also use gitlink:git-gui[1] to create commits, view changes in +the index and the working tree files, and individually select diff hunks +for inclusion in the index (by right-clicking on the diff hunk and +choosing "Stage Hunk For Commit"). + [[creating-good-commit-messages]] Creating good commit messages ----------------------------- @@ -1484,6 +1489,38 @@ $ git show HEAD^:path/to/file which will display the given version of the file. +[[interrupted-work]] +Temporarily setting aside work in progress +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While you are in the middle of working on something complicated, you +find an unrelated but obvious and trivial bug. You would like to fix it +before continuing. You can use gitlink:git-stash[1] to save the current +state of your work, and after fixing the bug (or, optionally after doing +so on a different branch and then coming back), unstash the +work-in-progress changes. + +------------------------------------------------ +$ git stash "work in progress for foo feature" +------------------------------------------------ + +This command will save your changes away to the `stash`, and +reset your working tree and the index to match the tip of your +current branch. Then you can make your fix as usual. + +------------------------------------------------ +... edit and test ... +$ git commit -a -m "blorpl: typofix" +------------------------------------------------ + +After that, you can go back to what you were working on with +`git stash apply`: + +------------------------------------------------ +$ git stash apply +------------------------------------------------ + + [[ensuring-good-performance]] Ensuring good performance ------------------------- @@ -1667,24 +1704,19 @@ one step: $ git pull origin master ------------------------------------------------- -In fact, "origin" is normally the default repository to pull from, -and the default branch is normally the HEAD of the remote repository, -so often you can accomplish the above with just +In fact, if you have "master" checked out, then by default "git pull" +merges from the HEAD branch of the origin repository. So often you can +accomplish the above with just a simple ------------------------------------------------- $ git pull ------------------------------------------------- -See the descriptions of the branch..remote and branch..merge -options in gitlink:git-config[1] to learn how to control these defaults -depending on the current branch. Also note that the --track option to -gitlink:git-branch[1] and gitlink:git-checkout[1] can be used to -automatically set the default remote branch to pull from at the time -that a branch is created: - -------------------------------------------------- -$ git checkout --track -b maint origin/maint -------------------------------------------------- +More generally, a branch that is created from a remote branch will pull +by default from that branch. See the descriptions of the +branch..remote and branch..merge options in +gitlink:git-config[1], and the discussion of the --track option in +gitlink:git-checkout[1], to learn how to control these defaults. In addition to saving you keystrokes, "git pull" also helps you by producing a default commit message documenting the branch and @@ -2479,8 +2511,10 @@ $ gitk origin..mywork & And browse through the list of patches in the mywork branch using gitk, applying them (possibly in a different order) to mywork-new using -cherry-pick, and possibly modifying them as you go using commit ---amend. +cherry-pick, and possibly modifying them as you go using commit --amend. +The git-gui[1] command may also help as it allows you to individually +select diff hunks for inclusion in the index (by right-clicking on the +diff hunk and choosing "Stage Hunk for Commit"). Another technique is to use git-format-patch to create a series of patches, then reset the state to before the patches:

NAME

DESCRIPTION

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

Preface

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

Preface

ChapterÂ 3.Â Developing with git

Telling git your name

ChapterÂ 3.Â Developing with git

Telling git your name

Creating good commit messages

Creating good commit messages

Ensuring good performance

Temporarily setting aside work in progress

Ensuring good performance

Ensuring reliability

Checking the repository for corruption

Other tools