-[[meta title="A tour of git: the basics"]]
+[[!meta title="A tour of git: the basics"]]
A tour of git: the basics
### 2.0 Copyright
* Gentoo
- emerge git
+ emerge dev-util/git
* OpenSUSE
command. If you are completely stuck, simply run “git help”; it will
print a brief list of commonly-used commands, along with a description
of what each does. If you ask for help on a specific command (such as
-"git help init"), it prints more detailed information. [XXX: Does "git
-help <foo>" work universally as a built-in or does it expect man to be
-present and just call out to "man git-<foo>"?]
+"git help init"), it prints more detailed information. [XXX: Does `git
+help <foo>` work universally as a built-in or does it expect man to be
+present and just call out to `man git-<foo>`?]
[XXX: The original hgbook includes the complete output of "hg
help init" at this point. I'm not including the corresponding
commit a1a0e8b392b17caf50325498df54802fe3c03710
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 15:43:07 2005 -0700
-
+
Trim comments.
-
+
commit 72d4f10e4a27dbb09ace1503c20dbac1912ee451
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 13:15:58 2005 -0700
-
+
Get make to generate the final binary from a .o file.
-
+
commit 13ed136b983a9c439eddeea8a1c2076cffbb685f
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 13:15:43 2005 -0700
-
+
Introduce a typo into hello.c.
-
+
commit 0a633bf58b45fcf1a8299d3c82cd1fd26d3f48f2
Author: Bryan O'Sullivan <mpm@selenic.com>
Date: Fri Aug 26 01:21:28 2005 -0700
-
+
Create a makefile
-
+
commit db7117a9dd9a6e57e8632ea5848e1101eee0fbde
Author: Bryan O'Sullivan <mpm@selenic.com>
Date: Fri Aug 26 01:20:50 2005 -0700
-
+
Create a standard "hello, world" program
-By default, this command prints a brief paragraph of output for each
-change to the project that was recorded. In git terminology, we
-call each of these recorded events a commit.
+This command prints a record of output for each change to the project
+that was recorded. In git terminology, we call each of these recorded
+events a commit.
-The fields in a record of output from “git log” are as follows.
+The default fields in a record of output from “git log” are as follows.
* commit This field consists of a string of 40 hexadecimal characters.
This is a unique identifier for referring to particular commits.
* Author The identity of the person who authored the commit. This
field consist of two sub-fields for the user's name and email
address, (or at least an email-like idenitifer). Note that git
- stores a separate "Committer" field for the person who commited
- the change, (since often an author will email a change to a
- maintainer that commits it). The "git log" command doesn't display
- the Committer, but other git tools do.
+ also stores a separate "Committer" field for the person who
+ commited the change, (since often an author will email a change to
+ a maintainer that commits it). See below for how to instruct "git
+ log" to display it as well.
* Date The date and time on which the commit was authored, (again
stored separately from the date the change was committed).
timezone in which it was created. (The date and time are displayed
entered to describe the commit, (generally a one-line summary
followed by more supporting text).
-The default output printed by “git log” is purely a summary; it is
-missing a lot of detail.
+The output of the "git log" command can be made more or less verbose
+by means of the --pretty option. For example, with "git log
+--pretty=short" the commit identifier will be omitted and only the
+first line of each commit message will be shown. And with "git log
+--pretty=fuller", (the name 'fuller' is in contrast to the default
+--pretty=full), the committer name and dates will be printed in
+addition to the author name and dates.
#### 2.4.1 Commits, revisions, and talking to other people
complete commit identifier, (perhaps in bug-tracking systems to
indicate a specific commit that fixes a bug, for example). But often,
in more casual settings, it's more convenient to use abbreviated
-commit identifiers. Git accept any unique prefix of a commit
-identifier, (and for reasonably-sized project the first 8 or 10
+commit identifiers. Git accepts any unique prefix of a commit
+identifier, (and for reasonably-sized projects the first 8 or 10
characters are almost always unique).
And unlike the permanent commit identifiers, git also provides
commit a1a0e8b392b17caf50325498df54802fe3c03710
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 15:43:07 2005 -0700
-
+
Trim comments.
-
+
commit 72d4f10e4a27dbb09ace1503c20dbac1912ee451
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 13:15:58 2005 -0700
-
+
Get make to generate the final binary from a .o file.
-
+
commit 13ed136b983a9c439eddeea8a1c2076cffbb685f
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 13:15:43 2005 -0700
-
+
Introduce a typo into hello.c.
#### 2.4.4 Other log filters
commit 72d4f10e4a27dbb09ace1503c20dbac1912ee451
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 13:15:58 2005 -0700
-
+
Get make to generate the final binary from a .o file.
-
+
commit 0a633bf58b45fcf1a8299d3c82cd1fd26d3f48f2
Author: Bryan O'Sullivan <mpm@selenic.com>
Date: Fri Aug 26 01:21:28 2005 -0700
-
+
Create a makefile
And "git log" can also filter based on the dates at which commits were
commit a1a0e8b392b17caf50325498df54802fe3c03710
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 15:43:07 2005 -0700
-
+
Trim comments.
-
+
hello.c | 8 ++------
1 files changed, 2 insertions(+), 6 deletions(-)
-
+
commit 72d4f10e4a27dbb09ace1503c20dbac1912ee451
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 13:15:58 2005 -0700
-
+
Get make to generate the final binary from a .o file.
-
+
Makefile | 2 ++
1 files changed, 2 insertions(+), 0 deletions(-)
-
+
commit 13ed136b983a9c439eddeea8a1c2076cffbb685f
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 13:15:43 2005 -0700
-
+
Introduce a typo into hello.c.
-
+
hello.c | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
Or perhaps you'd like to see the actual patch content of each change,
which you can get with -p. That commit with the word typo in its name
-looks suspicous, so let's tak a closer look. Remember that we can name
+looks suspicious, so let's take a closer look. Remember that we can name
it as master~3, HEAD~3, or any prefix of its commit identifier, (such
as 13ed136b):
commit 13ed136b983a9c439eddeea8a1c2076cffbb685f
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 13:15:43 2005 -0700
-
+
Introduce a typo into hello.c.
-
+
diff --git a/hello.c b/hello.c
index ed55ec0..80b260c 100644
--- a/hello.c
+++ b/hello.c
@@ -11,6 +11,6 @@
-
+
int main(int argc, char **argv)
{
- printf("hello, world!\n");
commit 13ed136b983a9c439eddeea8a1c2076cffbb685f
Author: Bryan O'Sullivan <bos@serpentine.com>
Date: Tue Sep 6 13:15:43 2005 -0700
-
+
Introduce a typo into hello.c.
-
+
diff --git a/hello.c b/hello.c
index ed55ec0..80b260c 100644
--- a/hello.c
+++ b/hello.c
@@ -11,6 +11,6 @@
-
+
int main(int argc, char **argv)
{
- printf("hello, world!\n");
systems.
* Most options have long names. For example, as we’ve already seen,
- the “git log" command accepts a --max-count=<number> option.
+ the “git log" command accepts a `--max-count=<number>` option.
* Some options have short, single-character names. Often these are
- aliases for long commands, (such as "-n <number>" instead of
- --max-count=<number>), but sometimes the option exists in
- short-form with no long-form equivalent, (such as -p). [XXX: It
- wouldn't hurt to fix this by adding --patch, etc. right?]
- * Long options start with two dashes (e.g. --max-count), while short
- options start with one (e.g. -n).
+ aliases for long commands, (such as `-n <number>` instead of
+ `--max-count=<number>`), but sometimes the option exists in
+ short-form with no long-form equivalent, (such as `-p`). [XXX: It
+ wouldn't hurt to fix this by adding `--patch`, etc. right?]
+ * Long options start with two dashes (e.g. `--max-count`), while short
+ options start with one (e.g. `-n`).
* Option naming and usage is consistent across commands. For
example, every command that lets you specify a commit identifier
After you've made that change, the “git status” command will tell you
what git knows about the files in the repository.
- $ ls
+ $ ls
hello.c Makefile
$ git status
# On branch master
no changes added to commit (use "git add" and/or "git commit -a")
First "git status" tells us that the current branch is "master". This
-means that the master branch is what will be updatea when we create a
+means that the master branch is what will be updated when we create a
new commit.
Note: In git a branch is a very simple notion---it's simply a name
--- a/hello.c
+++ b/hello.c
@@ -7,6 +7,6 @@
-
+
int main(int argc, char **argv)
{
- printf("hello, world!\");
#### 2.7.1 Introducing yourself to git
-Before we run "git commit" though, we should introduce ourself to git.
-Git records your name and address with each change that you commit,
-(as both author and committer unless you tell it otherwise), so that
-you and others will later be able to tell who made each change.
+Before you run "git commit" though, you should introduce yourself to
+git. Git records your name and email address with each change that
+you commit, (as both author and committer unless you tell it
+otherwise), so that you and others will later be able to tell who made
+each change.
Git tries to automatically figure out a sensible name and address to
attribute to both author and committer if you haven't explicitly told
the author and committer name and email as soon as a value is found):
1. If you specify a --author option to the “git commit” command on
- the command line, followed by a "Real Name <email@example.com>"
+ the command line, followed by a `"Real Name <email@example.com>"`
string, then this name and addresss will be used for the author
fields. The committer fields will still be determined as
below. This option is very helpful for when applying a commit
originally authored by someone other than yourself.
- 2. If any of the GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL,
- GIT_COMMITTER_NAME, or GIT_COMMITER_EMAIL environment variables
+ 2. If any of the `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`,
+ `GIT_COMMITTER`_NAME, or `GIT_COMMITER_EMAIL` environment variables
are set, then those values will be used for the corresponding
fields.
3. If you have a file in your home directory called .gitconfig, with
again with name or email settings in the [user] section, then
these values will be used to set any remaining author and
committer fields.
- 5. If you have set the EMAIL environment variable, this will be used
+ 5. If you have set the `EMAIL` environment variable, this will be used
to set author and committer email addresses if still unset.
6. git will query your system to find out your real name from
available GECOS field and your username, hostname, and domain to
error message instructing you how to use "git config" to tell git your
name and email address.
-You should think of the GIT_AUTHOR/COMMITER_NAME/EMAIL environment
+You should think of the `GIT_AUTHOR`/`COMMITER_NAME`/`EMAIL` environment
variables and the --author option to the “git commit” command as ways
to override git’s default selection. For normal use, the simplest and
most robust way to set your information is by creating a .gitconfig
then it will be there already). The initial contents of your
.gitconfig should look like this.
- # This is a git configuration file.
+ # This is a git configuration file.
[user]
name = Your Name
email = you@example.com
You can use any text you like as the value of the name and email
configuration items, since this information is for reading by other
people, not for interpreting by git. It is conventional to use your
-actual name as well as a valid email address. But some poepl, (notably
+actual name as well as a valid email address. But some people, (notably
Linus Torvalds, the original author of git), actually like the default
username@hostname convention that git falls back on without any
additional information about an email address. There's no requirement
Note: The -a on the command-line instructs git to commit the new
content of *all* tracked files that have been modified. This is a
convenience over explicitly listing filenames to be committed on the
-"git commit" command line. It is useful to use "git commit <files>"
+`git commit` command line. It is useful to use `git commit <files>`
when there is a need to commit only some subset of the files that have
been modified.
-If new files need to be committed for the first time, just use "git
-add <file>" before "git commit -a". If a file needs to be removed,
-just remove it as normal before committing and "git commit -a" will
+If new files need to be committed for the first time, just use `git
+add <file>` before `git commit -a`. If a file needs to be removed,
+just remove it as normal before committing and `git commit -a` will
notice that---it does not need to be explicitly told about the
removal.
-The editor that the “git commit” command drops us into will contain an
+The editor that the `git commit` command drops us into will contain an
empty line, followed by a number of lines starting with “#”. These
-lines contain the same information as seen in "git status" before:
+lines contain the same information as seen in `git status` before:
empty line
# Please enter the commit message for your changes.
#### 2.7.3 Writing a good commit message
A good commit message will generally have a single line that
-summarizes the commit, a blank line, and then one or more pargraphs
+summarizes the commit, a blank line, and then one or more paragraphs
with supporting detail. Since many tools only print the first line of
a commit message by default, it’s important that the first line stands
alone.
$ git log --pretty=short
commit 3ef5535144da88a854f7930503845cd44506c2e2
Author: Censored Person <censored.person@example.org>
-
+
include buildmeister/commondefs. Add an exports and install
As far as the remainder of the contents of the commit message are
the output of "git log --stat" or “git log -p", (so repeating the list
of all modified files is not useful, for example).
+To follow along with the example here, go ahead and type something
+like the following sentence into the editor. The misspelling here is
+intentional. You'll see how to fix that up after the fact in just a
+moment:
+
+ Fixed the typo so the program actuall complies now.
+
+Then save the file, and exit from the editor. When you do that, git
+will create the commit.
+
#### 2.7.4 Aborting a commit
If you decide that you don’t want to commit while in the middle of
commit fd21e5d6c5eedee70137229ebf348c25181812ab
Author: Carl Worth <cworth@cworth.org>
Date: Fri Sep 28 12:50:16 2007 -0700
-
+
Fixed the typo so the program actuall complies now.
-
+
diff --git a/hello.c b/hello.c
index 9a3ff79..ea364d3 100644
--- a/hello.c
+++ b/hello.c
@@ -7,6 +7,6 @@
-
+
int main(int argc, char **argv)
{
- printf("hello, world!\");
So now that we've cloned a local repository, made a change to the
code, setup our name and email address, and made a careful commit,
we're just about ready to share our change with the world. But wait,
-that commit message has some really embarrassing misspellings in
-it. Wouldn't it be nice to touch those up before I post this commit
+that commit message has that embarrassing misspelling in
+it. Wouldn't it be nice to touch that up before we post this commit
with a never-to-be-changed again commit identifier?
This is the exact situation for which "git commit --amend" was
-
-So I can just run that now and fix the broken commit message:
+invented. So you can just run that now and fix the broken commit
+message in the editor:
$ git commit --amend
commit 3c54ac672ec1130b36837f1b708054a7a1d402de
Author: Carl Worth <cworth@cworth.org>
Date: Fri Sep 28 12:50:16 2007 -0700
-
+
Fixed the typo so the program actually compiles now.
-
+
diff --git a/hello.c b/hello.c
index 9a3ff79..ea364d3 100644
--- a/hello.c
+++ b/hello.c
@@ -7,6 +7,6 @@
-
+
int main(int argc, char **argv)
{
- printf("hello, world!\");
One advantage of using git over some other systems is that the commit
speed is blazingly fast. The tool doesn't punish you at all for
-committing as often as you get our project into a state that is worth
-saving. "Commit early, commit often" is a well-supported mode of
-operation with git.
+committing every time your project is in a state worth saving. "Commit
+early, commit often" is a well-supported mode of operation with git.
### 2.8 Sharing changes
the progress-tracking spew were reduced to a single line. Something
like "Computing (100%) Transferring (100%)" or whatever.
-After (lots!) of progresss indication, git gives a report of which
+After (lots!) of progress indication, git gives a report of which
files were modified, (which is very useful for getting a quick feel
for what happened). If you would like more details on what changes
came in, git provides a range that is perfect for examining. Let's
commit 3c54ac672ec1130b36837f1b708054a7a1d402de
Author: Carl Worth <cworth@cworth.org>
Date: Fri Sep 28 12:50:16 2007 -0700
-
+
Fixed the typo so the program actually compiles now.
As expected, we received just the one commit.
Sometimes you may not know if you want to pull in the changes from the
remote repository or not. It's useful to be able to examine them
before accepting them into our branch. The "git pull" command shown in
-the previous section is conceptually the combination of two command,
+the previous section is conceptually the combination of two commands,
"git fetch" and "git merge". We can use these commands separately to
examine the change before accepting it.
commit 3c54ac672ec1130b36837f1b708054a7a1d402de
Author: Carl Worth <cworth@cworth.org>
Date: Fri Sep 28 12:50:16 2007 -0700
-
+
Fixed the typo so the program actually compiles now.
Another helpful way of visualizing what happened with "git fetch" here
is to run "gitk --all", which gives a graphical representation of all
branches. Here is what it would look like:
-[[img gitk-fetch.png]]
+[[!img gitk-fetch.png]]
Notice that origin/master points to a single commit that was committed
on top of the state pointed to by the "master" branch.
you are finished, you would issue a "git commit -a" to create the
merge commit.
-#### 2.8.3 Using "git remote" to pull changes other repositories
+#### 2.8.3 Using "git remote" to pull changes from other repositories
We've already described how "git pull" will pull in changes from the
repository which was the origin of the clone operation. Git also
These remote-tracking branches make it very easy to collaborate with
people as they are working on experimental features not yet ready for
upstream inclusion. For example, if fred's latest code is still
-trashing filesystems then he might not want to push it out the the
+trashing filesystems then he might not want to push it out to the
project's primary repository. But he may still want my help with
it. So he can push it to a branch in his own repository for which I've
got a remote. Then on my next "git fetch fred" I might notice a new
## Appendix D
Open Publication License
-Version 1.0, 8 June 1999
+Version 1.0, 8 June 1999
### D.1 Requirements on both unmodified and modified versions
incorporation of it by reference (with any options elected by the
author(s) and/or publisher) is displayed in the reproduction.
-Proper form for an incorporation by reference is as follows:
+Proper form for an incorporation by reference is as follows:
Copyright (c) year by author’s name or designee. This material may be
distributed only subject to the terms and conditions set forth in the
translations, anthologies, compilations and partial documents, must
meet the following requirements:
- 1. The modified version must be labeled as such.
+ 1. The modified version must be labeled as such.
2. The person making the modifications must be identified and the
modifications dated.
3. Acknowledgement of the original author and publisher if
applicable must be retained according to normal academic citation
practices.
- 4. The location of the original unmodified document must be identified.
+ 4. The location of the original unmodified document must be identified.
5. The original author’s (or authors’) name(s) may not be used to
assert or imply endorsement of the resulting document without the
original author’s (or authors’) permission.