undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
6219bb22ba
git-commit-vandalism/Documentation/user-manual.txt

4664 lines
170 KiB
Plaintext
Raw Normal View History

Call it "Git User Manual" and remove reference to very old Git version Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:55:15 +02:00
Git User Manual
_______________
user-manual: introduce git Well, we should say at least something about what git is. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-13 08:23:11 +02:00
Git is a fast distributed revision control system.
Documentation: Correct various misspellings and typos. Fix minor typos throughout the documentation. Signed-off-by: Brian Hetro <whee@smaertness.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-08-24 02:44:13 +02:00
This manual is designed to be readable by someone with basic UNIX
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
command-line skills, but no previous knowledge of Git.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
<<repositories-and-branches>> and <<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
regressions, and so on.
user-manual: add "quick start" as chapter 1 Add a "quick start" guide, modelled after Mercurial's, as the first chapter. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-21 03:41:48 +01:00
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
People needing to do actual development will also want to read
work around Python warnings from AsciiDoc It appears that a reference to an anchor defined as [[anchor-name]] from another place using <<anchor-name>> syntax, when the anchor name contains a string "-with-" in its name, triggers these warnings from Python interpreter. asciidoc -b docbook -d book user-manual.txt <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 There currently is no reference to "Finding comments with given content", but for consistency and for futureproofing, the anchor is also updated as the other ones that are actually used and trigger these warnings. Signed-off-by: Junio C Hamano <junio@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-08 03:38:46 +01:00
<<Developing-With-git>> and <<sharing-development>>.
Documentation: expand preface and todo's 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>
2007-01-08 04:58:14 +01:00
Further chapters cover more specialized topics.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Comprehensive reference documentation is available through the man
Documentation: user-manual: add information about "git help" at the beginning Talking about "git help" is useful because it has a few more features (like when using it without arguments or with "-a") and it may work on non unix like platforms. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-11-17 16:42:47 +01:00
pages, or linkgit:git-help[1] command. For example, for the command
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`git clone <repo>`, you can either use:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------------------
$ man git-clone
------------------------------------------------
Documentation: user-manual: add information about "git help" at the beginning Talking about "git help" is useful because it has a few more features (like when using it without arguments or with "-a") and it may work on non unix like platforms. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-11-17 16:42:47 +01:00
or:
------------------------------------------------
$ git help clone
------------------------------------------------
With the latter, you can use the manual viewer of your choice; see
linkgit:git-help[1] for more information.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
See also <<git-quick-start>> for a brief overview of Git commands,
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
without any explanation.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: quick-start updates 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>
2007-06-06 00:33:27 +02:00
Finally, see <<todo>> for ways that you can help make this manual more
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
complete.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[repositories-and-branches]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Repositories and Branches
=========================
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[how-to-get-a-git-repository]]
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
How to get a Git repository
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
---------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
It will be useful to have a Git repository to experiment with as you
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
read this manual.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The best way to get one is by using the linkgit:git-clone[1] command to
user-manual: minor editing for conciseness Just cutting out a few unnecessary words. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-06-07 00:41:43 +02:00
download a copy of an existing repository. If you don't already have a
project in mind, here are some interesting examples:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------------------
user-manual: Update download size for Git and the kernel They've grown since d19fbc3 (Documentation: add git user's manual, 2007-01-07) when the stats were initially added. I've rounded download sizes up to the nearest multiple of ten MiB to decrease the precision and give a bit of growing room. Exact sizes: $ git clone git://git.kernel.org/pub/scm/git/git.git Initialized empty Git repository in /tmp/git/.git/ remote: Counting objects: 156872, done. remote: Compressing objects: 100% (40826/40826), done. remote: Total 156872 (delta 115322), reused 155492 (delta 114094) Receiving objects: 100% (156872/156872), 37.29 MiB | 7.54 MiB/s, done. Resolving deltas: 100% (115322/115322), done. $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git Initialized empty Git repository in /tmp/linux/.git/ remote: Counting objects: 3057404, done. remote: Compressing objects: 100% (474769/474769), done. Receiving objects: 100% (3057404/3057404), 634.33 MiB | 27.95 MiB/s, done. remote: Total 3057404 (delta 2570385), reused 3040910 (delta 2554408) Resolving deltas: 100% (2570385/2570385), done. Checking out files: 100% (43012/43012), done. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-19 03:55:22 +02:00
# Git itself (approx. 40MB download):
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
$ git clone git://git.kernel.org/pub/scm/git/git.git
user-manual: Update download size for Git and the kernel They've grown since d19fbc3 (Documentation: add git user's manual, 2007-01-07) when the stats were initially added. I've rounded download sizes up to the nearest multiple of ten MiB to decrease the precision and give a bit of growing room. Exact sizes: $ git clone git://git.kernel.org/pub/scm/git/git.git Initialized empty Git repository in /tmp/git/.git/ remote: Counting objects: 156872, done. remote: Compressing objects: 100% (40826/40826), done. remote: Total 156872 (delta 115322), reused 155492 (delta 114094) Receiving objects: 100% (156872/156872), 37.29 MiB | 7.54 MiB/s, done. Resolving deltas: 100% (115322/115322), done. $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git Initialized empty Git repository in /tmp/linux/.git/ remote: Counting objects: 3057404, done. remote: Compressing objects: 100% (474769/474769), done. Receiving objects: 100% (3057404/3057404), 634.33 MiB | 27.95 MiB/s, done. remote: Total 3057404 (delta 2570385), reused 3040910 (delta 2554408) Resolving deltas: 100% (2570385/2570385), done. Checking out files: 100% (43012/43012), done. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-19 03:55:22 +02:00
# the Linux kernel (approx. 640MB download):
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------------------
The initial clone may be time-consuming for a large project, but you
will only need to clone once.
Documentation: Update 'linux-2.6.git' -> 'linux.git' The 3.x tree has been out for a while now. The -2.6 repository name survived the initial release [1], but kernel.org now only lists 'linux.git' (for aegl as well as torvalds) [2]. [1]: http://article.gmane.org/gmane.linux.kernel/1147422 On 2011-05-30 01:47:57 GMT, Linus Torvalds wrote: > ... yes, that means that my git tree is still called > "linux-2.6.git" on kernel.org. [2]: http://git.kernel.org/cgit/ Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-22 16:46:27 +02:00
The clone command creates a new directory named after the project
(`git` or `linux` in the examples above). After you cd into this
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
directory, you will see that it contains a copy of the project files,
user-manual: define "branch" and "working tree" at start Some explanation here might help. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 19:53:37 +01:00
called the <<def_working_tree,working tree>>, together with a special
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
top-level directory named `.git`, which contains all the information
user-manual: define "branch" and "working tree" at start Some explanation here might help. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 19:53:37 +01:00
about the history of the project.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[how-to-check-out]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
How to check out a different version of a project
-------------------------------------------------
user-manual: introduce the word "commit" earlier Use the word "commit" as a synonym for "version" from the start. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-19 04:16:24 +02:00
Git is best thought of as a tool for storing the history of a collection
of files. It stores the history as a compressed collection of
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
interrelated snapshots of the project's contents. In Git each such
user-manual: introduce the word "commit" earlier Use the word "commit" as a synonym for "version" from the start. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-19 04:16:24 +02:00
version is called a <<def_commit,commit>>.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: define "branch" and "working tree" at start Some explanation here might help. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 19:53:37 +01:00
Those snapshots aren't necessarily all arranged in a single line from
oldest to newest; instead, work may simultaneously proceed along
Documentation/user-manual.txt: fix typo Signed-off-by: Gustaf Hendeby <hendeby@isy.liu.se> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-12-31 14:31:35 +01:00
parallel lines of development, called <<def_branch,branches>>, which may
user-manual: define "branch" and "working tree" at start Some explanation here might help. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 19:53:37 +01:00
merge and diverge.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
A single Git repository can track development on multiple branches. It
user-manual: define "branch" and "working tree" at start Some explanation here might help. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 19:53:37 +01:00
does this by keeping a list of <<def_head,heads>> which reference the
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
latest commit on each branch; the linkgit:git-branch[1] command shows
user-manual: introduce "branch" and "branch head" differently 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>
2007-03-19 04:02:14 +01:00
you the list of branch heads:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------------------
$ git branch
* master
------------------------------------------------
user-manual: fix discussion of default clone 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>
2007-04-16 06:37:13 +02:00
A freshly cloned repository contains a single branch head, by default
named "master", with the working directory initialized to the state of
the project referred to by that branch head.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: introduce "branch" and "branch head" differently 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>
2007-03-19 04:02:14 +01:00
Most projects also use <<def_tag,tags>>. Tags, like heads, are
references into the project's history, and can be listed using the
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-tag[1] command:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------------------
$ git tag -l
v2.6.11
v2.6.11-tree
v2.6.12
v2.6.12-rc2
v2.6.12-rc3
v2.6.12-rc4
v2.6.12-rc5
v2.6.12-rc6
v2.6.13
...
------------------------------------------------
user-manual: clarify difference between tag and branch Explain the difference (well, one of the differences) between a tag and a branch. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-22 04:14:39 +01:00
Tags are expected to always point at the same version of a project,
user-manual: introduce "branch" and "branch head" differently 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>
2007-03-19 04:02:14 +01:00
while heads are expected to advance as development progresses.
user-manual: clarify difference between tag and branch Explain the difference (well, one of the differences) between a tag and a branch. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-22 04:14:39 +01:00
user-manual: introduce "branch" and "branch head" differently 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>
2007-03-19 04:02:14 +01:00
Create a new branch head pointing to one of these versions and check it
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
out using linkgit:git-checkout[1]:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------------------
$ git checkout -b new v2.6.13
------------------------------------------------
The working directory then reflects the contents that the project had
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
when it was tagged v2.6.13, and linkgit:git-branch[1] shows two
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
branches, with an asterisk marking the currently checked-out branch:
------------------------------------------------
$ git branch
master
* new
------------------------------------------------
If you decide that you'd rather see version 2.6.17, you can modify
the current branch to point at v2.6.17 instead, with
------------------------------------------------
$ git reset --hard v2.6.17
------------------------------------------------
user-manual: introduce "branch" and "branch head" differently 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>
2007-03-19 04:02:14 +01:00
Note that if the current branch head was your only reference to a
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
particular point in history, then resetting that branch may leave you
user-manual: introduce "branch" and "branch head" differently 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>
2007-03-19 04:02:14 +01:00
with no way to find the history it used to point to; so use this command
carefully.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[understanding-commits]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Understanding History: Commits
------------------------------
Every change in the history of a project is represented by a commit.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-show[1] command shows the most recent commit on the
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
current branch:
------------------------------------------------
$ git show
user-manual: use pithier example commit 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>
2007-08-19 17:14:21 +02:00
commit 17cf781661e6d38f737f15f53ab552f1e95960d7
Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)>
Date: Tue Apr 19 14:11:06 2005 -0700
Remove duplicate getenv(DB_ENVIRONMENT) call
Noted by Tony Luck.
diff --git a/init-db.c b/init-db.c
index 65898fa..b002dc6 100644
--- a/init-db.c
+++ b/init-db.c
@@ -7,7 +7,7 @@
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: use pithier example commit 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>
2007-08-19 17:14:21 +02:00
int main(int argc, char **argv)
{
- char *sha1_dir = getenv(DB_ENVIRONMENT), *path;
+ char *sha1_dir, *path;
int len, i;
if (mkdir(".git", 0755) < 0) {
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------------------
As you can see, a commit shows who made the latest change, what they
did, and why.
user-manual: insert earlier of mention content-addressable architecture 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>
2007-03-03 20:04:42 +01:00
Every commit has a 40-hexdigit id, sometimes called the "object name" or the
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
"SHA-1 id", shown on the first line of the `git show` output. You can usually
user-manual: insert earlier of mention content-addressable architecture 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>
2007-03-03 20:04:42 +01:00
refer to a commit by a shorter name, such as a tag or a branch name, but this
longer name can also be useful. Most importantly, it is a globally unique
name for this commit: so if you tell somebody else the object name (for
example in email), then you are guaranteed that name will refer to the same
commit in their repository that it does in yours (assuming their repository
has that commit at all). Since the object name is computed as a hash over the
contents of the commit, you are guaranteed that the commit can never change
without its name also changing.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
In fact, in <<git-concepts>> we shall see that everything stored in Git
user-manual: insert earlier of mention content-addressable architecture 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>
2007-03-03 20:04:42 +01:00
history, including file data and directory contents, is stored in an object
with a name that is a hash of its contents.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[understanding-reachability]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Understanding history: commits, parents, and reachability
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Every commit (except the very first commit in a project) also has a
parent commit which shows what happened before this commit.
Following the chain of parents will eventually take you back to the
beginning of the project.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
However, the commits do not form a simple list; Git allows lines of
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
development to diverge and then reconverge, and the point where two
lines of development reconverge is called a "merge". The commit
representing a merge can therefore have more than one parent, with
each parent representing the most recent commit on one of the lines
of development leading to that point.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The best way to see how this works is using the linkgit:gitk[1]
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
command; running gitk now on a Git repository and looking for merge
Fix some typos and improve wording Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:59:21 +02:00
commits will help understand how Git organizes history.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
In the following, we say that commit X is "reachable" from commit Y
if commit X is an ancestor of commit Y. Equivalently, you could say
Documentation: Correct various misspellings and typos. Fix minor typos throughout the documentation. Signed-off-by: Brian Hetro <whee@smaertness.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-08-24 02:44:13 +02:00
that Y is a descendant of X, or that there is a chain of parents
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
leading from commit Y to commit X.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[history-diagrams]]
Assorted typo fixes Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-04 05:49:16 +01:00
Understanding history: History diagrams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
We will sometimes represent Git history using diagrams like the one
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
below. Commits are shown as "o", and the links between them with
lines drawn with - / and \. Time goes left to right:
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
o--o--o <-- Branch A
/
o--o--o <-- master
\
o--o--o <-- Branch B
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
If we need to talk about a particular commit, the character "o" may
be replaced with another letter or number.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[what-is-a-branch]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Understanding history: What is a branch?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
user-manual: introduce "branch" and "branch head" differently 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>
2007-03-19 04:02:14 +01:00
When we need to be precise, we will use the word "branch" to mean a line
of development, and "branch head" (or just "head") to mean a reference
to the most recent commit on a branch. In the example above, the branch
head named "A" is a pointer to one particular commit, but we refer to
the line of three commits leading up to that point as all being part of
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
"branch A".
user-manual: introduce "branch" and "branch head" differently 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>
2007-03-19 04:02:14 +01:00
However, when no confusion will result, we often just use the term
"branch" both for branches and for branch heads.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[manipulating-branches]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Manipulating branches
---------------------
Creating, deleting, and modifying branches is quick and easy; here's
a summary of the commands:
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`git branch`::
Improve section "Manipulating branches" Add some missing punctuation. Simplify description of "git branch -d/-D". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:02:08 +02:00
list all branches.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`git branch <branch>`::
create a new branch named `<branch>`, referencing the same
Improve section "Manipulating branches" Add some missing punctuation. Simplify description of "git branch -d/-D". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:02:08 +02:00
point in history as the current branch.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`git branch <branch> <start-point>`::
create a new branch named `<branch>`, referencing
`<start-point>`, which may be specified any way you like,
Improve section "Manipulating branches" Add some missing punctuation. Simplify description of "git branch -d/-D". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:02:08 +02:00
including using a branch name or a tag name.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`git branch -d <branch>`::
Improve section "Manipulating branches" Add some missing punctuation. Simplify description of "git branch -d/-D". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:02:08 +02:00
delete the branch `<branch>`; if the branch is not fully
merged in its upstream branch or contained in the current branch,
this command will fail with a warning.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`git branch -D <branch>`::
Improve section "Manipulating branches" Add some missing punctuation. Simplify description of "git branch -d/-D". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:02:08 +02:00
delete the branch `<branch>` irrespective of its merged status.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`git checkout <branch>`::
make the current branch `<branch>`, updating the working
Improve section "Manipulating branches" Add some missing punctuation. Simplify description of "git branch -d/-D". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:02:08 +02:00
directory to reflect the version referenced by `<branch>`.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`git checkout -b <new> <start-point>`::
create a new branch `<new>` referencing `<start-point>`, and
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
check it out.
user-manual: detached HEAD 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>
2007-04-16 06:37:14 +02:00
The special symbol "HEAD" can always be used to refer to the current
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
branch. In fact, Git uses a file named `HEAD` in the `.git` directory
to remember which branch is current:
user-manual: detached HEAD 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>
2007-04-16 06:37:14 +02:00
------------------------------------------------
$ cat .git/HEAD
ref: refs/heads/master
------------------------------------------------
user-manual: use detached head when rewriting history 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>
2007-04-16 06:37:16 +02:00
[[detached-head]]
user-manual: detached HEAD 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>
2007-04-16 06:37:14 +02:00
Examining an old version without creating a new branch
------------------------------------------------------
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
The `git checkout` command normally expects a branch head, but will also
user-manual: detached HEAD 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>
2007-04-16 06:37:14 +02:00
accept an arbitrary commit; for example, you can check out the commit
referenced by a tag:
------------------------------------------------
$ git checkout v2.6.17
Use current "detached HEAD" message Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:56:04 +02:00
Note: checking out 'v2.6.17'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:
git checkout -b new_branch_name
user-manual: detached HEAD 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>
2007-04-16 06:37:14 +02:00
HEAD is now at 427abfa... Linux v2.6.17
------------------------------------------------
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
The HEAD then refers to the SHA-1 of the commit instead of to a branch,
user-manual: detached HEAD 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>
2007-04-16 06:37:14 +02:00
and git branch shows that you are no longer on a branch:
------------------------------------------------
$ cat .git/HEAD
427abfa28afedffadfca9dd8b067eb6d36bac53f
user-manual: more discussion of detached heads, fix typos 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>
2007-04-18 06:20:46 +02:00
$ git branch
Use current "detached HEAD" message Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:56:04 +02:00
* (detached from v2.6.17)
user-manual: detached HEAD 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>
2007-04-16 06:37:14 +02:00
master
------------------------------------------------
In this case we say that the HEAD is "detached".
user-manual: more discussion of detached heads, fix typos 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>
2007-04-18 06:20:46 +02:00
This is an easy way to check out a particular version without having to
make up a name for the new branch. You can still create a new branch
(or tag) for this version later if you decide to.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[examining-remote-branches]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Examining branches from a remote repository
-------------------------------------------
The "master" branch that was created at the time you cloned is a copy
of the HEAD in the repository that you cloned from. That repository
may also have had other branches, though, and your local repository
user-manual.txt: explain better the remote(-tracking) branch terms Now that the documentation is mostly consistant in the use of "remote branch" Vs "remote-tracking branch", let's make this distinction explicit early in the user-manual. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 22:06:20 +01:00
keeps branches which track each of those remote branches, called
remote-tracking branches, which you
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
can view using the `-r` option to linkgit:git-branch[1]:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------------------
$ git branch -r
origin/HEAD
origin/html
origin/maint
origin/man
origin/master
origin/next
origin/pu
origin/todo
------------------------------------------------
user-manual.txt: explain better the remote(-tracking) branch terms Now that the documentation is mostly consistant in the use of "remote branch" Vs "remote-tracking branch", let's make this distinction explicit early in the user-manual. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 22:06:20 +01:00
In this example, "origin" is called a remote repository, or "remote"
for short. The branches of this repository are called "remote
branches" from our point of view. The remote-tracking branches listed
above were created based on the remote branches at clone time and will
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
be updated by `git fetch` (hence `git pull`) and `git push`. See
user-manual.txt: explain better the remote(-tracking) branch terms Now that the documentation is mostly consistant in the use of "remote branch" Vs "remote-tracking branch", let's make this distinction explicit early in the user-manual. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 22:06:20 +01:00
<<Updating-a-repository-With-git-fetch>> for details.
user-manual: remote-tracking can be checked out, with detached HEAD Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 16:31:27 +01:00
You might want to build on one of these remote-tracking branches
on a branch of your own, just as you would for a tag:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------------------
$ git checkout -b my-todo-copy origin/todo
------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
You can also check out `origin/todo` directly to examine it or
user-manual: remote-tracking can be checked out, with detached HEAD Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 16:31:27 +01:00
write a one-off patch. See <<detached-head,detached head>>.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Note that the name "origin" is just the name that Git uses by default
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
to refer to the repository that you cloned from.
[[how-git-stores-references]]
user-manual: update references discussion 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>
2007-01-22 04:31:07 +01:00
Naming branches, tags, and other references
-------------------------------------------
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Branches, remote-tracking branches, and tags are all references to
user-manual: update references discussion 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>
2007-01-22 04:31:07 +01:00
commits. All references are named with a slash-separated path name
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
starting with `refs`; the names we've been using so far are actually
user-manual: update references discussion 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>
2007-01-22 04:31:07 +01:00
shorthand:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
- The branch `test` is short for `refs/heads/test`.
- The tag `v2.6.18` is short for `refs/tags/v2.6.18`.
- `origin/master` is short for `refs/remotes/origin/master`.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: update references discussion 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>
2007-01-22 04:31:07 +01:00
The full name is occasionally useful if, for example, there ever
exists a tag and a branch with the same name.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
(Newly created refs are actually stored in the `.git/refs` directory,
user-manual: don't assume refs are stored under .git/refs The scripts taken from Tony Luck's howto assume all refs can be found under .git/refs, but this is not necessarily true, especially since git-gc runs git-pack-refs. Also add a note warning of this in the chapter that introduces refs, and fix the same incorrect assumption in one other spot. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-10 04:07:02 +02:00
under the path given by their name. However, for efficiency reasons
they may also be packed together in a single file; see
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-pack-refs[1]).
user-manual: don't assume refs are stored under .git/refs The scripts taken from Tony Luck's howto assume all refs can be found under .git/refs, but this is not necessarily true, especially since git-gc runs git-pack-refs. Also add a note warning of this in the chapter that introduces refs, and fix the same incorrect assumption in one other spot. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-10 04:07:02 +02:00
user-manual: miscellaneous editing 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>
2007-05-07 06:56:45 +02:00
As another useful shortcut, the "HEAD" of a repository can be referred
to just using the name of that repository. So, for example, "origin"
is usually a shortcut for the HEAD branch in the repository "origin".
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
For the complete list of paths which Git checks for references, and
user-manual: update references discussion 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>
2007-01-22 04:31:07 +01:00
the order it uses to decide which to choose when there are multiple
references with the same shorthand name, see the "SPECIFYING
Documentation: gitrevisions is in section 7 Fix references to gitrevisions(1) in the manual pages and HTML documentation. In practice, this will not matter much unless someone tries to use a hard copy of the git reference manual. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-11 18:03:32 +02:00
REVISIONS" section of linkgit:gitrevisions[7].
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
work around Python warnings from AsciiDoc It appears that a reference to an anchor defined as [[anchor-name]] from another place using <<anchor-name>> syntax, when the anchor name contains a string "-with-" in its name, triggers these warnings from Python interpreter. asciidoc -b docbook -d book user-manual.txt <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 There currently is no reference to "Finding comments with given content", but for consistency and for futureproofing, the anchor is also updated as the other ones that are actually used and trigger these warnings. Signed-off-by: Junio C Hamano <junio@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-08 03:38:46 +01:00
[[Updating-a-repository-With-git-fetch]]
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Updating a repository with git fetch
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------
Eventually the developer cloned from will do additional work in her
repository, creating new commits and advancing the branches to point
at the new commits.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
The command `git fetch`, with no arguments, will update all of the
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
remote-tracking branches to the latest version found in her
repository. It will not touch any of your own branches--not even the
"master" branch that was created for you on clone.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[fetching-branches]]
Documentation: begin discussion of git-remote in user manual Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 06:18:09 +01:00
Fetching branches from other repositories
-----------------------------------------
You can also track branches from repositories other than the one you
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
cloned from, using linkgit:git-remote[1]:
Documentation: begin discussion of git-remote in user manual Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 06:18:09 +01:00
-------------------------------------------------
Documentation: Update the NFS remote examples to use the staging repo linux-nfs.org seems to have restructured their repository layout since 8391c60 (git-remote.txt: fix example url, 2007-11-02), and Bruce's repo is now at git://git.linux-nfs.org/projects/bfields/linux.git. Bruce also has a more richer internal branch structure (master, everything, for-3.1, ...), so updating the existing example to use his current repo may be confusing. To simplify, I've replaced the NFS repo with Greg's staging repo. I've also updated the output of the surrounding commands to match the output of a current run through. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-22 16:46:26 +02:00
$ git remote add staging git://git.kernel.org/.../gregkh/staging.git
$ git fetch staging
...
From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging
* [new branch] master -> staging/master
* [new branch] staging-linus -> staging/staging-linus
* [new branch] staging-next -> staging/staging-next
Documentation: begin discussion of git-remote in user manual Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 06:18:09 +01:00
-------------------------------------------------
New remote-tracking branches will be stored under the shorthand name
Documentation: Update the NFS remote examples to use the staging repo linux-nfs.org seems to have restructured their repository layout since 8391c60 (git-remote.txt: fix example url, 2007-11-02), and Bruce's repo is now at git://git.linux-nfs.org/projects/bfields/linux.git. Bruce also has a more richer internal branch structure (master, everything, for-3.1, ...), so updating the existing example to use his current repo may be confusing. To simplify, I've replaced the NFS repo with Greg's staging repo. I've also updated the output of the surrounding commands to match the output of a current run through. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-22 16:46:26 +02:00
that you gave `git remote add`, in this case `staging`:
Documentation: begin discussion of git-remote in user manual Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 06:18:09 +01:00
-------------------------------------------------
$ git branch -r
Documentation: Update the NFS remote examples to use the staging repo linux-nfs.org seems to have restructured their repository layout since 8391c60 (git-remote.txt: fix example url, 2007-11-02), and Bruce's repo is now at git://git.linux-nfs.org/projects/bfields/linux.git. Bruce also has a more richer internal branch structure (master, everything, for-3.1, ...), so updating the existing example to use his current repo may be confusing. To simplify, I've replaced the NFS repo with Greg's staging repo. I've also updated the output of the surrounding commands to match the output of a current run through. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-22 16:46:26 +02:00
origin/HEAD -> origin/master
origin/master
staging/master
staging/staging-linus
staging/staging-next
Documentation: begin discussion of git-remote in user manual Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 06:18:09 +01:00
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
If you run `git fetch <remote>` later, the remote-tracking branches
for the named `<remote>` will be updated.
Documentation: begin discussion of git-remote in user manual Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 06:18:09 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
If you examine the file `.git/config`, you will see that Git has added
Documentation: begin discussion of git-remote in user manual Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 06:18:09 +01:00
a new stanza:
-------------------------------------------------
$ cat .git/config
...
Documentation: Update the NFS remote examples to use the staging repo linux-nfs.org seems to have restructured their repository layout since 8391c60 (git-remote.txt: fix example url, 2007-11-02), and Bruce's repo is now at git://git.linux-nfs.org/projects/bfields/linux.git. Bruce also has a more richer internal branch structure (master, everything, for-3.1, ...), so updating the existing example to use his current repo may be confusing. To simplify, I've replaced the NFS repo with Greg's staging repo. I've also updated the output of the surrounding commands to match the output of a current run through. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-22 16:46:26 +02:00
[remote "staging"]
url = git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git
fetch = +refs/heads/*:refs/remotes/staging/*
Documentation: begin discussion of git-remote in user manual Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 06:18:09 +01:00
...
-------------------------------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
This is what causes Git to track the remote's branches; you may modify
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
or delete these configuration options by editing `.git/config` with a
user-manual: add references to git-config man page 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>
2007-01-29 06:17:51 +01:00
text editor. (See the "CONFIGURATION FILE" section of
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-config[1] for details.)
Documentation: begin discussion of git-remote in user manual Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 06:18:09 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[exploring-git-history]]
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Exploring Git history
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
=====================
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
user-manual: fix typolets. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-07-24 10:58:51 +02:00
the contents of a file hierarchy, together with "commits" which show
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
the relationships between these snapshots.
Git provides extremely flexible and fast tools for exploring the
history of a project.
Fix some documentation typos and grammar Also suggest user manual mention .gitignore. Signed-off-by: Michael Coleman <tutufan@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-02 07:25:30 +01:00
We start with one specialized tool that is useful for finding the
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
commit that introduced a bug into a project.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[using-bisect]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
How to use bisect to find a regression
--------------------------------------
Suppose version 2.6.18 of your project worked, but the version at
"master" crashes. Sometimes the best way to find the cause of such a
regression is to perform a brute-force search through the project's
history to find the particular commit that caused the problem. The
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-bisect[1] command can help you do this:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git bisect start
$ git bisect good v2.6.18
$ git bisect bad master
Bisecting: 3537 revisions left to test after this
[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
If you run `git branch` at this point, you'll see that Git has
documentation: user-manual: update "using-bisect" section Since version 1.5.6 "git bisect" doesn't use a "bisect" branch any more, but the user manual had not been updated to reflect this. So this patch does that and while at it also adds a few words about "git bisect skip" and points user to the "git bisect" man page for more information. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-31 05:22:40 +02:00
temporarily moved you in "(no branch)". HEAD is now detached from any
branch and points directly to a commit (with commit id 65934...) that
is reachable from "master" but not from v2.6.18. Compile and test it,
and see whether it crashes. Assume it does crash. Then:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git bisect bad
Bisecting: 1769 revisions left to test after this
[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
-------------------------------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
checks out an older version. Continue like this, telling Git at each
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
stage whether the version it gives you is good or bad, and notice
that the number of revisions left to test is cut approximately in
half each time.
After about 13 tests (in this case), it will output the commit id of
the guilty commit. You can then examine the commit with
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-show[1], find out who wrote it, and mail them your bug
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
report with the commit id. Finally, run
-------------------------------------------------
$ git bisect reset
-------------------------------------------------
documentation: user-manual: update "using-bisect" section Since version 1.5.6 "git bisect" doesn't use a "bisect" branch any more, but the user manual had not been updated to reflect this. So this patch does that and while at it also adds a few words about "git bisect skip" and points user to the "git bisect" man page for more information. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-31 05:22:40 +02:00
to return you to the branch you were on before.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Note that the version which `git bisect` checks out for you at each
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
point is just a suggestion, and you're free to try a different
version if you think it would be a good idea. For example,
occasionally you may land on a commit that broke something unrelated;
run
-------------------------------------------------
Documentation: A few minor fixes to Git User's Manual 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>
2007-04-03 18:27:28 +02:00
$ git bisect visualize
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
which will run gitk and label the commit it chose with a marker that
user-manual: typo and grammar fixes Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-08 22:00:30 +02:00
says "bisect". Choose a safe-looking commit nearby, note its commit
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
id, and check it out with:
-------------------------------------------------
$ git reset --hard fb47ddb2db...
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
then test, run `bisect good` or `bisect bad` as appropriate, and
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
continue.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Instead of `git bisect visualize` and then `git reset --hard
fb47ddb2db...`, you might just want to tell Git that you want to skip
documentation: user-manual: update "using-bisect" section Since version 1.5.6 "git bisect" doesn't use a "bisect" branch any more, but the user manual had not been updated to reflect this. So this patch does that and while at it also adds a few words about "git bisect skip" and points user to the "git bisect" man page for more information. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-31 05:22:40 +02:00
the current commit:
-------------------------------------------------
$ git bisect skip
-------------------------------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
In this case, though, Git may not eventually be able to tell the first
Fix typos in the documentation. Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-11-27 08:32:01 +01:00
bad one between some first skipped commits and a later bad commit.
documentation: user-manual: update "using-bisect" section Since version 1.5.6 "git bisect" doesn't use a "bisect" branch any more, but the user manual had not been updated to reflect this. So this patch does that and while at it also adds a few words about "git bisect skip" and points user to the "git bisect" man page for more information. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-31 05:22:40 +02:00
There are also ways to automate the bisecting process if you have a
test script that can tell a good from a bad commit. See
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
linkgit:git-bisect[1] for more information about this and other `git
bisect` features.
documentation: user-manual: update "using-bisect" section Since version 1.5.6 "git bisect" doesn't use a "bisect" branch any more, but the user manual had not been updated to reflect this. So this patch does that and while at it also adds a few words about "git bisect skip" and points user to the "git bisect" man page for more information. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-31 05:22:40 +02:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[naming-commits]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Naming commits
--------------
We have seen several ways of naming commits already:
user-manual: SHA1 -> object name Prefer "object name" to SHA1, at least in higher level documentation. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-29 08:16:45 +01:00
- 40-hexdigit object name
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
- branch name: refers to the commit at the head of the given
branch
- tag name: refers to the commit pointed to by the given tag
(we've seen branches and tags are special cases of
<<how-git-stores-references,references>>).
- HEAD: refers to the head of the current branch
User manual: fix typos in examples 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>
2007-01-11 03:11:53 +01:00
There are many more; see the "SPECIFYING REVISIONS" section of the
Documentation: gitrevisions is in section 7 Fix references to gitrevisions(1) in the manual pages and HTML documentation. In practice, this will not matter much unless someone tries to use a hard copy of the git reference manual. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-11 18:03:32 +02:00
linkgit:gitrevisions[7] man page for the complete list of ways to
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
name revisions. Some examples:
-------------------------------------------------
user-manual: SHA1 -> object name Prefer "object name" to SHA1, at least in higher level documentation. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-29 08:16:45 +01:00
$ git show fb47ddb2 # the first few characters of the object name
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
# are usually enough to specify it uniquely
$ git show HEAD^ # the parent of the HEAD commit
$ git show HEAD^^ # the grandparent
$ git show HEAD~4 # the great-great-grandparent
-------------------------------------------------
Recall that merge commits may have more than one parent; by default,
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`^` and `~` follow the first parent listed in the commit, but you can
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
also choose:
-------------------------------------------------
$ git show HEAD^1 # show the first parent of HEAD
$ git show HEAD^2 # show the second parent of HEAD
-------------------------------------------------
In addition to HEAD, there are several other special names for
commits:
Merges (to be discussed later), as well as operations such as
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
`git reset`, which change the currently checked-out commit, generally
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
set ORIG_HEAD to the value HEAD had before the current operation.
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
The `git fetch` operation always stores the head of the last fetched
branch in FETCH_HEAD. For example, if you run `git fetch` without
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
specifying a local branch as the target of the operation
-------------------------------------------------
$ git fetch git://example.com/proj.git theirbranch
-------------------------------------------------
the fetched commits will still be available from FETCH_HEAD.
When we discuss merges we'll also see the special name MERGE_HEAD,
which refers to the other branch that we're merging in to the current
branch.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-rev-parse[1] command is a low-level command that is
user-manual: SHA1 -> object name Prefer "object name" to SHA1, at least in higher level documentation. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-29 08:16:45 +01:00
occasionally useful for translating some name for a commit to the object
name for that commit:
Documentation: rev-list -> rev-parse, other typos, start examples Fix some typos, start adding some more simple examples. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:17:00 +01:00
-------------------------------------------------
$ git rev-parse origin
e05db0fd4f31dde7005f075a84f96b360d05984b
-------------------------------------------------
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[creating-tags]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Creating tags
-------------
We can also create a tag to refer to a particular commit; after
running
-------------------------------------------------
Documentation: A few minor fixes to Git User's Manual 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>
2007-04-03 18:27:28 +02:00
$ git tag stable-1 1b2e1d63ff
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
You can use `stable-1` to refer to the commit 1b2e1d63ff.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: miscellaneous editing 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>
2007-05-07 06:56:45 +02:00
This creates a "lightweight" tag. If you would also like to include a
comment with the tag, and possibly sign it cryptographically, then you
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
should create a tag object instead; see the linkgit:git-tag[1] man page
user-manual: miscellaneous editing 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>
2007-05-07 06:56:45 +02:00
for details.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[browsing-revisions]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Browsing revisions
------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-log[1] command can show lists of commits. On its
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
own, it shows all commits reachable from the parent commit; but you
can also make more specific requests:
-------------------------------------------------
$ git log v2.5.. # commits since (not reachable from) v2.5
$ git log test..master # commits reachable from master but not test
$ git log master..test # ...reachable from test but not master
$ git log master...test # ...reachable from either test or master,
# but not both
$ git log --since="2 weeks ago" # commits from the last 2 weeks
$ git log Makefile # commits which modify Makefile
$ git log fs/ # ... which modify any file under fs/
$ git log -S'foo()' # commits which add or remove any file data
# matching the string 'foo()'
-------------------------------------------------
And of course you can combine all of these; the following finds
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
commits since v2.5 which touch the `Makefile` or any file under `fs`:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git log v2.5.. Makefile fs/
-------------------------------------------------
You can also ask git log to show patches:
-------------------------------------------------
$ git log -p
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
See the `--pretty` option in the linkgit:git-log[1] man page for more
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
display options.
Note that git log starts with the most recent commit and works
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
backwards through the parents; however, since Git history can contain
Assorted typo fixes Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-04 05:49:16 +01:00
multiple independent lines of development, the particular order that
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
commits are listed in may be somewhat arbitrary.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[generating-diffs]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Generating diffs
----------------
You can generate diffs between any two versions using
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-diff[1]:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git diff master..test
-------------------------------------------------
user-manual: mention "..." in "Generating diffs", etc. We should mention the use of the "..." syntax for git-diff here. The note about the difference between diff and the combined output of git-format-patch then no longer fits so well, so remove it. Add a reference to the git-format-patch[1] manpage. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-19 01:18:27 +01:00
That will produce the diff between the tips of the two branches. If
you'd prefer to find the diff from their common ancestor to test, you
can use three dots instead of two:
-------------------------------------------------
$ git diff master...test
-------------------------------------------------
Sometimes what you want instead is a set of patches; for this you can
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
use linkgit:git-format-patch[1]:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git format-patch master..test
-------------------------------------------------
will generate a file with a patch for each commit reachable from test
user-manual: mention "..." in "Generating diffs", etc. We should mention the use of the "..." syntax for git-diff here. The note about the difference between diff and the combined output of git-format-patch then no longer fits so well, so remove it. Add a reference to the git-format-patch[1] manpage. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-19 01:18:27 +01:00
but not from master.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[viewing-old-file-versions]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Viewing old file versions
-------------------------
You can always view an old version of a file by just checking out the
correct revision first. But sometimes it is more convenient to be
able to view an old version of a single file without checking
anything out; this command does that:
-------------------------------------------------
$ git show v2.5:fs/locks.c
-------------------------------------------------
Before the colon may be anything that names a commit, and after it
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
may be any path to a file tracked by Git.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[history-examples]]
Documentation: rev-list -> rev-parse, other typos, start examples Fix some typos, start adding some more simple examples. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:17:00 +01:00
Examples
--------
user-manual: add a "counting commits" example This is partly just an excuse to mention --pretty= and rev-list. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-13 08:14:45 +02:00
[[counting-commits-on-a-branch]]
Counting the number of commits on a branch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Suppose you want to know how many commits you've made on `mybranch`
since it diverged from `origin`:
user-manual: add a "counting commits" example This is partly just an excuse to mention --pretty= and rev-list. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-13 08:14:45 +02:00
-------------------------------------------------
$ git log --pretty=oneline origin..mybranch | wc -l
-------------------------------------------------
Alternatively, you may often see this sort of thing done with the
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
lower-level command linkgit:git-rev-list[1], which just lists the SHA-1's
user-manual: add a "counting commits" example This is partly just an excuse to mention --pretty= and rev-list. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-13 08:14:45 +02:00
of all the given commits:
-------------------------------------------------
$ git rev-list origin..mybranch | wc -l
-------------------------------------------------
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[checking-for-equal-branches]]
Documentation: rev-list -> rev-parse, other typos, start examples Fix some typos, start adding some more simple examples. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:17:00 +01:00
Check whether two branches point at the same history
user-manual: rewrap, fix heading levels Fix some heading levels that prevented compile; rewrap some stuff. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-15 04:43:47 +01:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: rev-list -> rev-parse, other typos, start examples Fix some typos, start adding some more simple examples. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:17:00 +01:00
Suppose you want to check whether two branches point at the same point
in history.
-------------------------------------------------
$ git diff origin..master
-------------------------------------------------
user-manual: reindent Just some minor reindenting Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-14 22:29:40 +01:00
will tell you whether the contents of the project are the same at the
two branches; in theory, however, it's possible that the same project
contents could have been arrived at by two different historical
user-manual: SHA1 -> object name Prefer "object name" to SHA1, at least in higher level documentation. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-29 08:16:45 +01:00
routes. You could compare the object names:
Documentation: rev-list -> rev-parse, other typos, start examples Fix some typos, start adding some more simple examples. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:17:00 +01:00
-------------------------------------------------
$ git rev-list origin
e05db0fd4f31dde7005f075a84f96b360d05984b
$ git rev-list master
e05db0fd4f31dde7005f075a84f96b360d05984b
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Or you could recall that the `...` operator selects all commits
Fix some typos and improve wording Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:59:21 +02:00
reachable from either one reference or the other but not
user-manual: Fix 'both: so' -> 'both; so' typo The clause "so `git log ...` will return no commits..." is independent, not a description of "both", so a semicolon is more appropriate. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-10 16:10:36 +01:00
both; so
Documentation: rev-list -> rev-parse, other typos, start examples Fix some typos, start adding some more simple examples. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:17:00 +01:00
-------------------------------------------------
$ git log origin...master
-------------------------------------------------
will return no commits when the two branches are equal.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[finding-tagged-descendants]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Find first tagged version including a given fix
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: rev-list -> rev-parse, other typos, start examples Fix some typos, start adding some more simple examples. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:17:00 +01:00
user-manual: reindent Just some minor reindenting Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-14 22:29:40 +01:00
Suppose you know that the commit e05db0fd fixed a certain problem.
You'd like to find the earliest tagged release that contains that
fix.
Of course, there may be more than one answer--if the history branched
after commit e05db0fd, then there could be multiple "earliest" tagged
releases.
You could just visually inspect the commits since e05db0fd:
-------------------------------------------------
$ gitk e05db0fd..
-------------------------------------------------
Fix some typos and improve wording Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:59:21 +02:00
or you can use linkgit:git-name-rev[1], which will give the commit a
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
name based on any tag it finds pointing to one of the commit's
descendants:
-------------------------------------------------
Documentation: A few minor fixes to Git User's Manual 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>
2007-04-03 18:27:28 +02:00
$ git name-rev --tags e05db0fd
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
e05db0fd tags/v1.5.0-rc1^0~23
-------------------------------------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-describe[1] command does the opposite, naming the
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
revision using a tag on which the given commit is based:
-------------------------------------------------
$ git describe e05db0fd
Documentation: A few minor fixes to Git User's Manual 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>
2007-04-03 18:27:28 +02:00
v1.5.0-rc0-260-ge05db0f
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
but that may sometimes help you guess which tags might come after the
given commit.
If you just want to verify whether a given tagged version contains a
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
given commit, you could use linkgit:git-merge-base[1]:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
$ git merge-base e05db0fd v1.5.0-rc1
e05db0fd4f31dde7005f075a84f96b360d05984b
-------------------------------------------------
The merge-base command finds a common ancestor of the given commits,
and always returns one or the other in the case where one is a
descendant of the other; so the above output shows that e05db0fd
actually is an ancestor of v1.5.0-rc1.
Alternatively, note that
-------------------------------------------------
user-manual: document git-show-branch example 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>
2007-01-29 07:55:33 +01:00
$ git log v1.5.0-rc1..e05db0fd
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: document git-show-branch example 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>
2007-01-29 07:55:33 +01:00
will produce empty output if and only if v1.5.0-rc1 includes e05db0fd,
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
because it outputs only commits that are not reachable from v1.5.0-rc1.
Documentation: rev-list -> rev-parse, other typos, start examples Fix some typos, start adding some more simple examples. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:17:00 +01:00
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
As yet another alternative, the linkgit:git-show-branch[1] command lists
user-manual: document git-show-branch example 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>
2007-01-29 07:55:33 +01:00
the commits reachable from its arguments with a display on the left-hand
Fix some typos and improve wording Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:59:21 +02:00
side that indicates which arguments that commit is reachable from.
So, if you run something like
user-manual: document git-show-branch example 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>
2007-01-29 07:55:33 +01:00
-------------------------------------------------
$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2
! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
available
! [v1.5.0-rc0] GIT v1.5.0 preview
! [v1.5.0-rc1] GIT v1.5.0-rc1
! [v1.5.0-rc2] GIT v1.5.0-rc2
...
-------------------------------------------------
Fix some typos and improve wording Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:59:21 +02:00
then a line like
user-manual: document git-show-branch example 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>
2007-01-29 07:55:33 +01:00
-------------------------------------------------
+ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
available
-------------------------------------------------
Fix some typos and improve wording Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:59:21 +02:00
shows that e05db0fd is reachable from itself, from v1.5.0-rc1,
and from v1.5.0-rc2, and not from v1.5.0-rc0.
user-manual: document git-show-branch example 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>
2007-01-29 07:55:33 +01:00
user-manual: listing commits reachable from some refs not others This is just an amusing example raised by someone in irc. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-14 04:58:06 +02:00
[[showing-commits-unique-to-a-branch]]
Showing commits unique to a given branch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
user-manual: document git-show-branch example 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>
2007-01-29 07:55:33 +01:00
user-manual: listing commits reachable from some refs not others This is just an amusing example raised by someone in irc. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-14 04:58:06 +02:00
Suppose you would like to see all the commits reachable from the branch
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
head named `master` but not from any other head in your repository.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: listing commits reachable from some refs not others This is just an amusing example raised by someone in irc. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-14 04:58:06 +02:00
We can list all the heads in this repository with
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-show-ref[1]:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: listing commits reachable from some refs not others This is just an amusing example raised by someone in irc. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-14 04:58:06 +02:00
-------------------------------------------------
$ git show-ref --heads
bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial
db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint
a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
24dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2
1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
-------------------------------------------------
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
We can get just the branch-head names, and remove `master`, with
user-manual: listing commits reachable from some refs not others This is just an amusing example raised by someone in irc. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-14 04:58:06 +02:00
the help of the standard utilities cut and grep:
-------------------------------------------------
$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master'
refs/heads/core-tutorial
refs/heads/maint
refs/heads/tutorial-2
refs/heads/tutorial-fixes
-------------------------------------------------
And then we can ask to see all the commits reachable from master
but not from these other heads:
-------------------------------------------------
$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 |
grep -v '^refs/heads/master' )
-------------------------------------------------
Obviously, endless variations are possible; for example, to see all
commits reachable from some head but not from any tag in the repository:
-------------------------------------------------
user-manual: fixed typo in example Signed-off-by: Steffen Prohaska <prohaska@zib.de> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-05-26 21:16:27 +02:00
$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )
user-manual: listing commits reachable from some refs not others This is just an amusing example raised by someone in irc. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-14 04:58:06 +02:00
-------------------------------------------------
Documentation: gitrevisions is in section 7 Fix references to gitrevisions(1) in the manual pages and HTML documentation. In practice, this will not matter much unless someone tries to use a hard copy of the git reference manual. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-11 18:03:32 +02:00
(See linkgit:gitrevisions[7] for explanations of commit-selecting
user-manual: listing commits reachable from some refs not others This is just an amusing example raised by someone in irc. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-14 04:58:06 +02:00
syntax such as `--not`.)
user-manual: move howto/make-dist.txt into user manual 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>
2007-05-13 06:14:40 +02:00
[[making-a-release]]
Creating a changelog and tarball for a software release
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-archive[1] command can create a tar or zip archive from
user-manual: move howto/make-dist.txt into user manual 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>
2007-05-13 06:14:40 +02:00
any version of a project; for example:
-------------------------------------------------
user-manual: use -o latest.tar.gz to create a gzipped tarball This functionality was introduced by 0e804e09 (archive: provide builtin .tar.gz filter, 2011-07-21) for v1.7.7. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:16:01 +01:00
$ git archive -o latest.tar.gz --prefix=project/ HEAD
user-manual: move howto/make-dist.txt into user manual 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>
2007-05-13 06:14:40 +02:00
-------------------------------------------------
user-manual: use -o latest.tar.gz to create a gzipped tarball This functionality was introduced by 0e804e09 (archive: provide builtin .tar.gz filter, 2011-07-21) for v1.7.7. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:16:01 +01:00
will use HEAD to produce a gzipped tar archive in which each filename
is preceded by `project/`. The output file format is inferred from
the output file extension if possible, see linkgit:git-archive[1] for
details.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Versions of Git older than 1.7.7 don't know about the `tar.gz` format,
user-manual: use -o latest.tar.gz to create a gzipped tarball This functionality was introduced by 0e804e09 (archive: provide builtin .tar.gz filter, 2011-07-21) for v1.7.7. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:16:01 +01:00
you'll need to use gzip explicitly:
-------------------------------------------------
$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
-------------------------------------------------
user-manual: move howto/make-dist.txt into user manual 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>
2007-05-13 06:14:40 +02:00
If you're releasing a new version of a software project, you may want
to simultaneously make a changelog to include in the release
announcement.
Linus Torvalds, for example, makes new kernel releases by tagging them,
then running:
-------------------------------------------------
$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7
-------------------------------------------------
where release-script is a shell script that looks like:
-------------------------------------------------
#!/bin/sh
stable="$1"
last="$2"
new="$3"
echo "# git tag v$new"
echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz"
echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz"
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.
user-manual: document git-show-branch example 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>
2007-01-29 07:55:33 +01:00
user-manual: fix anchor name Finding-comments-With-given-Content Change the anchor name to Finding-commits-With-given-Content so that it corresponds to the actual content there. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-09-28 13:16:07 +02:00
[[Finding-commits-With-given-Content]]
user-manual: finding commits referencing given file content 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>
2007-05-19 06:37:25 +02:00
Finding commits referencing a file with given content
user-manual: fix incorrect header level This section is a subsection of the "Examples" section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-20 17:12:09 +02:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
user-manual: finding commits referencing given file content 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>
2007-05-19 06:37:25 +02:00
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:
-------------------------------------------------
manual: Fix example finding commits referencing given content. If I'm handed a file, then it typically lives outside the working directory. git-log only operates on in-tree files, so the first 'filename' should be an in-tree one, or it should look at all files. This patch does the latter, so it would also find renamed files. However, it is also slower. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:02:19 +02:00
$ git log --raw --abbrev=40 --pretty=oneline |
user-manual: finding commits referencing given file content 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>
2007-05-19 06:37:25 +02:00
grep -B 1 `git hash-object filename`
-------------------------------------------------
Figuring out why this works is left as an exercise to the (advanced)
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and
linkgit:git-hash-object[1] man pages may prove helpful.
user-manual: finding commits referencing given file content 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>
2007-05-19 06:37:25 +02:00
work around Python warnings from AsciiDoc It appears that a reference to an anchor defined as [[anchor-name]] from another place using <<anchor-name>> syntax, when the anchor name contains a string "-with-" in its name, triggers these warnings from Python interpreter. asciidoc -b docbook -d book user-manual.txt <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 There currently is no reference to "Finding comments with given content", but for consistency and for futureproofing, the anchor is also updated as the other ones that are actually used and trigger these warnings. Signed-off-by: Junio C Hamano <junio@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-08 03:38:46 +01:00
[[Developing-With-git]]
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Developing with Git
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
===================
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[telling-git-your-name]]
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Telling Git your name
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
---------------------
user-manual: use 'git config --global user.*' for setup A simple command line call is easier than spawning an editor, especially for folks new to ideas like the "command line" and "text editors". This is also the approach suggested by 'git commit' if you try and commit without having configured user.name or user.email. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:58 +01:00
Before creating any commits, you should introduce yourself to Git.
The easiest way to do so is to use linkgit:git-config[1]:
------------------------------------------------
$ git config --global user.name 'Your Name Comes Here'
$ git config --global user.email 'you@yourdomain.example.com'
------------------------------------------------
Which will add the following to a file named `.gitconfig` in your
home directory:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------------------------------------------
[user]
name = Your Name Comes Here
email = you@yourdomain.example.com
------------------------------------------------
user-manual: use 'git config --global user.*' for setup A simple command line call is easier than spawning an editor, especially for folks new to ideas like the "command line" and "text editors". This is also the approach suggested by 'git commit' if you try and commit without having configured user.name or user.email. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:58 +01:00
See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
details on the configuration file. The file is plain text, so you can
also edit it with your favorite editor.
user-manual: add references to git-config man page 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>
2007-01-29 06:17:51 +01:00
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[creating-a-new-repository]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Creating a new repository
-------------------------
Creating a new repository from scratch is very easy:
-------------------------------------------------
$ mkdir project
$ cd project
user-manual: replace init-db by init Replace mentions of init-db by mentions of init. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 18:44:08 +01:00
$ git init
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
If you have some initial content (say, a tarball):
-------------------------------------------------
Be consistent in switch usage for tar tar handles switches with and witout preceding '-', but the documentation should be consistent nonetheless. Signed-off-by: Henrik Austad <henrik@austad.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-01-05 16:25:37 +01:00
$ tar xzvf project.tar.gz
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
$ cd project
user-manual: replace init-db by init Replace mentions of init-db by mentions of init. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 18:44:08 +01:00
$ git init
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
$ git add . # include everything below ./ in the first commit:
$ git commit
-------------------------------------------------
[[how-to-make-a-commit]]
usermanual.txt: some capitalization nits Signed-off-by: Arjen Laarhoven <arjen@yaph.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-07 01:48:36 +02:00
How to make a commit
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
--------------------
Creating a new commit takes three steps:
1. Making some changes to the working directory using your
favorite editor.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
2. Telling Git about your changes.
3. Creating the commit using the content you told Git about
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
in step 2.
In practice, you can interleave and repeat steps 1 and 2 as many
times as you want: in order to keep track of what you want committed
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
at step 3, Git maintains a snapshot of the tree's contents in a
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
special staging area called "the index."
user manual: answer some comments from Junio Junio left a few comments in his previous patch; deal with each of them. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:23:37 +01:00
At the beginning, the content of the index will be identical to
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
that of the HEAD. The command `git diff --cached`, which shows
user manual: answer some comments from Junio Junio left a few comments in his previous patch; deal with each of them. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:23:37 +01:00
the difference between the HEAD and the index, should therefore
produce no output at that point.
User manual: fix typos in examples 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>
2007-01-11 03:11:53 +01:00
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Modifying the index is easy:
Simplify "How to make a commit" Combine the two cases for "git add" into one. Add verb "use" to "git rm" case. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:01:17 +02:00
To update the index with the contents of a new or modified file, use
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git add path/to/file
-------------------------------------------------
Simplify "How to make a commit" Combine the two cases for "git add" into one. Add verb "use" to "git rm" case. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:01:17 +02:00
To remove a file from the index and from the working tree, use
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git rm path/to/file
-------------------------------------------------
After each step you can verify that
-------------------------------------------------
$ git diff --cached
-------------------------------------------------
always shows the difference between the HEAD and the index file--this
is what you'd commit if you created the commit now--and that
-------------------------------------------------
$ git diff
-------------------------------------------------
shows the difference between the working tree and the index file.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Note that `git add` always adds just the current contents of a file
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
to the index; further changes to the same file will be ignored unless
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
you run `git add` on the file again.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
When you're ready, just run
-------------------------------------------------
$ git commit
-------------------------------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
and Git will prompt you for a commit message and then create the new
Assorted typo fixes Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-04 05:49:16 +01:00
commit. Check to make sure it looks like what you expected with
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git show
-------------------------------------------------
As a special shortcut,
War on whitespace 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>
2007-06-07 09:04:01 +02:00
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git commit -a
-------------------------------------------------
will update the index with any files that you've modified or removed
and create a commit, all in one step.
A number of commands are useful for keeping track of what you're
about to commit:
-------------------------------------------------
$ git diff --cached # difference between HEAD and the index; what
user-manual: fix typolets. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-07-24 10:58:51 +02:00
# would be committed if you ran "commit" now.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
$ git diff # difference between the index file and your
# working directory; changes that would not
# be included if you ran "commit" now.
user-manual: miscellaneous editing 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>
2007-05-07 06:56:45 +02:00
$ git diff HEAD # difference between HEAD and working tree; what
# would be committed if you ran "commit -a" now.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
$ git status # a brief per-file summary of the above.
-------------------------------------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
You can also use linkgit:git-gui[1] to create commits, view changes in
user-manual: mention git-gui 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>
2007-08-06 00:12:37 +02:00
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").
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[creating-good-commit-messages]]
usermanual.txt: some capitalization nits Signed-off-by: Arjen Laarhoven <arjen@yaph.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-07 01:48:36 +02:00
Creating good commit messages
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-----------------------------
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
Documentation: describe subject more precisely The discussion of email subject throughout the documentation is misleading; it indicates that the first line will always become the subject. In fact, the subject is generally all lines up until the first full blank line. This patch refines that, and makes more use of the concept of a commit title, with the title being all text up to the first blank line. Signed-off-by: Jeremy White <jwhite@codeweavers.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-14 00:27:09 +02:00
description. The text up to the first blank line in a commit
message is treated as the commit title, and that title is used
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
throughout Git. For example, linkgit:git-format-patch[1] turns a
Documentation: describe subject more precisely The discussion of email subject throughout the documentation is misleading; it indicates that the first line will always become the subject. In fact, the subject is generally all lines up until the first full blank line. This patch refines that, and makes more use of the concept of a commit title, with the title being all text up to the first blank line. Signed-off-by: Jeremy White <jwhite@codeweavers.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-14 00:27:09 +02:00
commit into email, and it uses the title on the Subject line and the
rest of the commit in the body.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Add section on ignoring files 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>
2007-05-16 02:31:40 +02:00
[[ignoring-files]]
Ignoring files
--------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
A project will often generate files that you do 'not' want to track with Git.
user-manual: Add section on ignoring files 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>
2007-05-16 02:31:40 +02:00
This typically includes files generated by a build process or temporary
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
backup files made by your editor. Of course, 'not' tracking files with Git
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
is just a matter of 'not' calling `git add` on them. But it quickly becomes
user-manual: Add section on ignoring files 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>
2007-05-16 02:31:40 +02:00
annoying to have these untracked files lying around; e.g. they make
Documentation: remove extra quoting/emphasis around literal texts If literal text (asciidoc `...`) can be rendered in a differently from normal text for each output format (man, HTML), then we do not need extra quotes or other wrapping around inline literal text segments. config.txt Change '`...`' to `...`. In asciidoc, the single quotes provide emphasis, literal text should be distintive enough. Change "`...`" to `...`. These double quotes do not work if present in the described config value, so drop them. git-checkout.txt Change "`...`" to `...` or `"..."`. All instances are command line argument examples. One "`-`" becomes `-`. Two others are involve curly braces, so move the double quotes inside the literal region to indicate that they might need to be quoted on the command line of certain shells (tcsh). git-merge.txt Change "`...`" to `...`. All instances are used to describe merge conflict markers. The quotes should are not important. git-rev-parse.txt Change "`...`" to `...`. All instances are around command line arguments where no in-shell quoting should be necessary. gitcli.txt Change `"..."` to `...`. All instances are around command line examples or single command arguments. They do not semanticly belong inside the literal text, and they are not needed outside it. glossary-content.txt user-manual.txt Change "`...`" to `...`. All instances were around command lines. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-15 12:30:52 +01:00
`git add .` practically useless, and they keep showing up in the output of
`git status`.
user-manual: Add section on ignoring files 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>
2007-05-16 02:31:40 +02:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
You can tell Git to ignore certain files by creating a file called
`.gitignore` in the top level of your working directory, with contents
such as:
user-manual: Add section on ignoring files 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>
2007-05-16 02:31:40 +02:00
-------------------------------------------------
# Lines starting with '#' are considered comments.
user-manual: edit "ignoring files" for conciseness 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>
2007-05-25 02:28:14 +02:00
# Ignore any file named foo.txt.
user-manual: Add section on ignoring files 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>
2007-05-16 02:31:40 +02:00
foo.txt
# Ignore (generated) html files,
*.html
# except foo.html which is maintained by hand.
!foo.html
# Ignore objects and archives.
*.[oa]
-------------------------------------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
See linkgit:gitignore[5] for a detailed explanation of the syntax. You can
user-manual: edit "ignoring files" for conciseness 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>
2007-05-25 02:28:14 +02:00
also place .gitignore files in other directories in your working tree, and they
will apply to those directories and their subdirectories. The `.gitignore`
files can be added to your repository like any other files (just run `git add
.gitignore` and `git commit`, as usual), which is convenient when the exclude
patterns (such as patterns matching build output files) would also make sense
for other users who clone your repository.
If you wish the exclude patterns to affect only certain repositories
(instead of every repository for a given project), you may instead put
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
them in a file in your repository named `.git/info/exclude`, or in any
file specified by the `core.excludesfile` configuration variable.
Some Git commands can also take exclude patterns directly on the
command line. See linkgit:gitignore[5] for the details.
user-manual: Add section on ignoring files 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>
2007-05-16 02:31:40 +02:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[how-to-merge]]
usermanual.txt: some capitalization nits Signed-off-by: Arjen Laarhoven <arjen@yaph.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-07 01:48:36 +02:00
How to merge
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
------------
You can rejoin two diverging branches of development using
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-merge[1]:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git merge branchname
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
merges the development in the branch `branchname` into the current
user-manual: Document that "git merge" doesn't like uncommited changes. We explain the user why uncommited changes can be problematic with merge, and point to "commit" and "stash" for the solution. While talking about commited Vs uncommited changes, we also make it clear that the result of a merge is normally commited. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-22 23:26:18 +01:00
branch.
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
A merge is made by combining the changes made in `branchname` and the
user-manual: Document that "git merge" doesn't like uncommited changes. We explain the user why uncommited changes can be problematic with merge, and point to "commit" and "stash" for the solution. While talking about commited Vs uncommited changes, we also make it clear that the result of a merge is normally commited. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-22 23:26:18 +01:00
changes made up to the latest commit in your current branch since
their histories forked. The work tree is overwritten by the result of
the merge when this combining is done cleanly, or overwritten by a
half-merged results when this combining results in conflicts.
Therefore, if you have uncommitted changes touching the same files as
the ones impacted by the merge, Git will refuse to proceed. Most of
the time, you will want to commit your changes before you can merge,
and if you don't, then linkgit:git-stash[1] can take these changes
away while you're doing the merge, and reapply them afterwards.
Fix typos in technical documentation. Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-31 14:24:39 +01:00
If the changes are independent enough, Git will automatically complete
user-manual: Document that "git merge" doesn't like uncommited changes. We explain the user why uncommited changes can be problematic with merge, and point to "commit" and "stash" for the solution. While talking about commited Vs uncommited changes, we also make it clear that the result of a merge is normally commited. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-22 23:26:18 +01:00
the merge and commit the result (or reuse an existing commit in case
of <<fast-forwards,fast-forward>>, see below). On the other hand,
if there are conflicts--for example, if the same file is
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
modified in two different ways in the remote branch and the local
branch--then you are warned; the output may look something like this:
-------------------------------------------------
user-manual: fix inconsistent use of pull and merge 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>
2007-03-11 03:52:39 +01:00
$ git merge next
100% (4/4) done
Auto-merged file.txt
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
CONFLICT (content): Merge conflict in file.txt
Automatic merge failed; fix conflicts and then commit the result.
-------------------------------------------------
Conflict markers are left in the problematic files, and after
you resolve the conflicts manually, you can update the index
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
with the contents and run Git commit, as you normally would when
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
creating a new file.
If you examine the resulting commit using gitk, you will see that it
has two parents, one pointing to the top of the current branch, and
one to the top of the other branch.
[[resolving-a-merge]]
Resolving a merge
-----------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
When a merge isn't resolved automatically, Git leaves the index and
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
the working tree in a special state that gives you all the
information you need to help resolve the merge.
Files with conflicts are marked specially in the index, so until you
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
resolve the problem and update the index, linkgit:git-commit[1] will
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
fail:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git commit
file.txt: needs merge
-------------------------------------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
Also, linkgit:git-status[1] will list those files as "unmerged", and the
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
files with conflicts will have conflict markers added, like this:
-------------------------------------------------
<<<<<<< HEAD:file.txt
Hello world
=======
Goodbye
>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
-------------------------------------------------
All you need to do is edit the files to resolve the conflicts, and then
-------------------------------------------------
$ git add file.txt
$ git commit
-------------------------------------------------
Note that the commit message will already be filled in for you with
some information about the merge. Normally you can just use this
default message unchanged, but you may add additional commentary of
your own if desired.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
The above is all you need to know to resolve a simple merge. But Git
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
also provides more information to help resolve conflicts:
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[conflict-resolution]]
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
Getting conflict-resolution help during a merge
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
All of the changes that Git was able to merge automatically are
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
already added to the index file, so linkgit:git-diff[1] shows only
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
the conflicts. It uses an unusual syntax:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git diff
diff --cc file.txt
index 802992c,2b60207..0000000
--- a/file.txt
+++ b/file.txt
@@@ -1,1 -1,1 +1,5 @@@
++<<<<<<< HEAD:file.txt
+Hello world
++=======
+ Goodbye
++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
-------------------------------------------------
user-manual: fix typolets. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-07-24 10:58:51 +02:00
Recall that the commit which will be committed after we resolve this
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
conflict will have two parents instead of the usual one: one parent
will be HEAD, the tip of the current branch; the other will be the
tip of the other branch, which is stored temporarily in MERGE_HEAD.
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
During the merge, the index holds three versions of each file. Each of
these three "file stages" represents a different version of the file:
-------------------------------------------------
$ git show :1:file.txt # the file in a common ancestor of both branches
user-manual: describe how higher stages are set during a merge Higher stages store the blobs involved from their side verbatim. Removal of uninteresting hunks are done by "diff --cc" upon demand and not stored in the index. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-12 23:30:37 +02:00
$ git show :2:file.txt # the version from HEAD.
$ git show :3:file.txt # the version from MERGE_HEAD.
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
-------------------------------------------------
user-manual: describe how higher stages are set during a merge Higher stages store the blobs involved from their side verbatim. Removal of uninteresting hunks are done by "diff --cc" upon demand and not stored in the index. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-12 23:30:37 +02:00
When you ask linkgit:git-diff[1] to show the conflicts, it runs a
three-way diff between the conflicted merge results in the work tree with
stages 2 and 3 to show only hunks whose contents come from both sides,
mixed (in other words, when a hunk's merge results come only from stage 2,
that part is not conflicting and is not shown. Same for stage 3).
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
The diff above shows the differences between the working-tree version of
file.txt and the stage 2 and stage 3 versions. So instead of preceding
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
each line by a single `+` or `-`, it now uses two columns: the first
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
column is used for differences between the first parent and the working
directory copy, and the second for differences between the second parent
and the working directory copy. (See the "COMBINED DIFF FORMAT" section
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
of linkgit:git-diff-files[1] for a details of the format.)
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
After resolving the conflict in the obvious way (but before updating the
index), the diff will look like:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git diff
diff --cc file.txt
index 802992c,2b60207..0000000
--- a/file.txt
+++ b/file.txt
@@@ -1,1 -1,1 +1,1 @@@
- Hello world
-Goodbye
++Goodbye world
-------------------------------------------------
This shows that our resolved version deleted "Hello world" from the
first parent, deleted "Goodbye" from the second parent, and added
"Goodbye world", which was previously absent from both.
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
Some special diff options allow diffing the working directory against
any of these stages:
-------------------------------------------------
$ git diff -1 file.txt # diff against stage 1
$ git diff --base file.txt # same as the above
$ git diff -2 file.txt # diff against stage 2
$ git diff --ours file.txt # same as the above
$ git diff -3 file.txt # diff against stage 3
$ git diff --theirs file.txt # same as the above.
-------------------------------------------------
Documentation: fix gitlinks Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-03 06:54:38 +02:00
The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
for merges:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git log --merge
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
$ gitk --merge
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
These will display all commits which exist only on HEAD or on
MERGE_HEAD, and which touch an unmerged file.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
You may also use linkgit:git-mergetool[1], which lets you merge the
Use capitalized names where appropriate The Linux kernel and Emacs are both spelled capitalized Signed-off-by: Henrik Austad <henrik@austad.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-01-05 16:25:36 +01:00
unmerged files using external tools such as Emacs or kdiff3.
user-manual: miscellaneous editing 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>
2007-05-07 06:56:45 +02:00
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
Each time you resolve the conflicts in a file and update the index:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git add file.txt
-------------------------------------------------
user-manual: more detailed merge discussion 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>
2007-03-03 21:34:27 +01:00
the different stages of that file will be "collapsed", after which
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
`git diff` will (by default) no longer show diffs for that file.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
[[undoing-a-merge]]
usermanual.txt: some capitalization nits Signed-off-by: Arjen Laarhoven <arjen@yaph.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-07 01:48:36 +02:00
Undoing a merge
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
---------------
If you get stuck and decide to just give up and throw the whole mess
away, you can always return to the pre-merge state with
-------------------------------------------------
$ git reset --hard HEAD
-------------------------------------------------
user-manual: fix typolets. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-07-24 10:58:51 +02:00
Or, if you've already committed the merge that you want to throw away,
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
user-manual: reset to ORIG_HEAD not HEAD to undo merge 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>
2007-02-20 00:46:09 +01:00
$ git reset --hard ORIG_HEAD
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
However, this last command can be dangerous in some cases--never
throw away a commit you have already committed if that commit may
itself have been merged into another branch, as doing so may confuse
further merges.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[fast-forwards]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Fast-forward merges
-------------------
There is one special case not mentioned above, which is treated
differently. Normally, a merge results in a merge commit, with two
parents, one pointing at each of the two lines of development that
were merged.
user-manual: clean up fast-forward and dangling-objects sections 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
2007-04-30 17:11:02 +02:00
However, if the current branch is a descendant of the other--so every
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
commit present in the one is already contained in the other--then Git
Use 'fast-forward' all over the place It's a compound word. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-24 10:31:32 +02:00
just performs a "fast-forward"; the head of the current branch is moved
user-manual: clean up fast-forward and dangling-objects sections 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
2007-04-30 17:11:02 +02:00
forward to point at the head of the merged-in branch, without any new
commits being created.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[fixing-mistakes]]
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
Fixing mistakes
---------------
If you've messed up the working tree, but haven't yet committed your
mistake, you can return the entire working tree to the last committed
state with
-------------------------------------------------
$ git reset --hard HEAD
-------------------------------------------------
If you make a commit that you later wish you hadn't, there are two
fundamentally different ways to fix the problem:
1. You can create a new commit that undoes whatever was done
user-manual: minor rewording for clarity. Junio screwed up when applying the previous round of the patch; rewording from "previous" to "old" does make the description clearer. Also revert the rewording from head to branch. The description is talking about the branch's tip commit and using the word head is clearer. Based on input from Sergei and Bruce. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-14 21:08:15 +01:00
by the old commit. This is the correct thing if your
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
mistake has already been made public.
2. You can go back and modify the old commit. You should
never do this if you have already made the history public;
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Git does not normally expect the "history" of a project to
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
change, and cannot correctly perform repeated merges from
a branch that has had its history changed.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[reverting-a-commit]]
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
Fixing a mistake with a new commit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Creating a new commit that reverts an earlier change is very easy;
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
just pass the linkgit:git-revert[1] command a reference to the bad
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
commit; for example, to revert the most recent commit:
-------------------------------------------------
$ git revert HEAD
-------------------------------------------------
This will create a new commit which undoes the change in HEAD. You
will be given a chance to edit the commit message for the new commit.
You can also revert an earlier change, for example, the next-to-last:
-------------------------------------------------
$ git revert HEAD^
-------------------------------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
In this case Git will attempt to undo the old change while leaving
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
intact any changes made since then. If more recent changes overlap
with the changes to be reverted, then you will be asked to fix
conflicts manually, just as in the case of <<resolving-a-merge,
resolving a merge>>.
user-manual: clarify language about "modifying" old commits It's important to remember that git doesn't really allowing "editing" or "modifying" commits, only replacing them by new commits. Redo some of the language to make this clearer. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-26 01:01:57 +01:00
[[fixing-a-mistake-by-rewriting-history]]
Fixing a mistake by rewriting history
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the problematic commit is the most recent commit, and you have not
yet made that commit public, then you may just
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
<<undoing-a-merge,destroy it using `git reset`>>.
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
Alternatively, you
can edit the working directory and update the index to fix your
mistake, just as if you were going to <<how-to-make-a-commit,create a
new commit>>, then run
-------------------------------------------------
$ git commit --amend
-------------------------------------------------
which will replace the old commit by a new commit incorporating your
changes, giving you a chance to edit the old commit message first.
Again, you should never do this to a commit that may already have
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
been merged into another branch; use linkgit:git-revert[1] instead in
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
that case.
user-manual: clarify language about "modifying" old commits It's important to remember that git doesn't really allowing "editing" or "modifying" commits, only replacing them by new commits. Redo some of the language to make this clearer. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-26 01:01:57 +01:00
It is also possible to replace commits further back in the history, but
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
this is an advanced topic to be left for
<<cleaning-up-history,another chapter>>.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[checkout-of-path]]
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
Checking out an old version of a file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the process of undoing a previous bad change, you may find it
useful to check out an older version of a particular file using
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
linkgit:git-checkout[1]. We've used `git checkout` before to switch
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
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
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-show[1]:
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
-------------------------------------------------
user-manual: fix missing colon in git-show example 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>
2007-03-11 04:00:12 +01:00
$ git show HEAD^:path/to/file
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
-------------------------------------------------
which will display the given version of the file.
user-manual: mention git stash Mention the git-stash command as a way to temporarily set aside work in progress. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-04 00:22:59 +02:00
[[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
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
before continuing. You can use linkgit:git-stash[1] to save the current
user-manual: mention git stash Mention the git-stash command as a way to temporarily set aside work in progress. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-04 00:22:59 +02:00
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.
------------------------------------------------
User-manual: "git stash <comment>" form is long gone These days you must explicitly say "git stash save <comment>". Signed-off-by: William Pursell <bill.pursell@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-02-03 23:41:14 +01:00
$ git stash save "work in progress for foo feature"
user-manual: mention git stash Mention the git-stash command as a way to temporarily set aside work in progress. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-04 00:22:59 +02:00
------------------------------------------------
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
Documentation: teach stash/pop workflow instead of stash/apply Recent discussion on the list showed some comments in favour of a stash/pop workflow: http://marc.info/?l=git&m=124234911423358&w=2 http://marc.info/?l=git&m=124235348327711&w=2 Change the stash documentation and examples to document pop in its own right (and apply in terms of pop), and use stash/pop in the examples. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-05-28 11:40:15 +02:00
`git stash pop`:
user-manual: mention git stash Mention the git-stash command as a way to temporarily set aside work in progress. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-04 00:22:59 +02:00
------------------------------------------------
Documentation: teach stash/pop workflow instead of stash/apply Recent discussion on the list showed some comments in favour of a stash/pop workflow: http://marc.info/?l=git&m=124234911423358&w=2 http://marc.info/?l=git&m=124235348327711&w=2 Change the stash documentation and examples to document pop in its own right (and apply in terms of pop), and use stash/pop in the examples. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-05-28 11:40:15 +02:00
$ git stash pop
user-manual: mention git stash Mention the git-stash command as a way to temporarily set aside work in progress. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-04 00:22:59 +02:00
------------------------------------------------
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[ensuring-good-performance]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Ensuring good performance
-------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
On large repositories, Git depends on compression to keep the history
user-manual: Rewrite git-gc section for automatic packing This should have happened back in 2007, when `git gc` learned about auto (e9831e8, git-gc --auto: add documentation, 2007-09-17). Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-10 16:10:27 +01:00
information from taking up too much space on disk or in memory. Some
Merge branch 'maint' * maint: user-manual: Rewrite git-gc section for automatic packing user-manual: Fix 'you - Git' -> 'you--Git' typo user-manual: Fix 'http' -> 'HTTP' typos user-manual: Fix 'both: so' -> 'both; so' typo
2013-02-11 05:40:44 +01:00
Git commands may automatically run linkgit:git-gc[1], so you don't
user-manual: Rewrite git-gc section for automatic packing This should have happened back in 2007, when `git gc` learned about auto (e9831e8, git-gc --auto: add documentation, 2007-09-17). Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-10 16:10:27 +01:00
have to worry about running it manually. However, compressing a large
repository may take a while, so you may want to call `gc` explicitly
to avoid automatic compression kicking in when it is not convenient.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[ensuring-reliability]]
user-manual: stub discussion of fsck and reflog Have some sort of recovery/reliability section that deals with reflog and fsck. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-26 06:17:12 +01:00
Ensuring reliability
--------------------
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[checking-for-corruption]]
user-manual: stub discussion of fsck and reflog Have some sort of recovery/reliability section that deals with reflog and fsck. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-26 06:17:12 +01:00
Checking the repository for corruption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-fsck[1] command runs a number of self-consistency checks
user-manual: rewrap a few long lines Rewrap some long lines. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-29 07:33:55 +01:00
on the repository, and reports on any problems. This may take some
fsck: --no-dangling omits "dangling object" information The default output from "fsck" is often overwhelmed by informational message on dangling objects, especially if you do not repack often, and a real error can easily be buried. Add "--no-dangling" option to omit them, and update the user manual to demonstrate its use. Based on a patch by Clemens Buchacher, but reverted the part to change the default to --no-dangling, which is unsuitable for the first patch. The usual three-step procedure to break the backward compatibility over time needs to happen on top of this, if we were to go in that direction. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-02-28 23:55:39 +01:00
time.
user-manual: git-fsck, dangling objects 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>
2007-01-29 05:29:19 +01:00
-------------------------------------------------
user-manual: fsck-objects -> fsck There seems to be an agreement to rename fsck-objects to fsck. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-29 05:31:47 +01:00
$ git fsck
user-manual: git-fsck, dangling objects 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>
2007-01-29 05:29:19 +01:00
dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb
dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f
dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e
dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
...
-------------------------------------------------
fsck: --no-dangling omits "dangling object" information The default output from "fsck" is often overwhelmed by informational message on dangling objects, especially if you do not repack often, and a real error can easily be buried. Add "--no-dangling" option to omit them, and update the user manual to demonstrate its use. Based on a patch by Clemens Buchacher, but reverted the part to change the default to --no-dangling, which is unsuitable for the first patch. The usual three-step procedure to break the backward compatibility over time needs to happen on top of this, if we were to go in that direction. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-02-28 23:55:39 +01:00
You will see informational messages on dangling objects. They are objects
that still exist in the repository but are no longer referenced by any of
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
your branches, and can (and will) be removed after a while with `gc`.
Documentation: spelling fixes Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-06-19 19:56:09 +02:00
You can run `git fsck --no-dangling` to suppress these messages, and still
fsck: --no-dangling omits "dangling object" information The default output from "fsck" is often overwhelmed by informational message on dangling objects, especially if you do not repack often, and a real error can easily be buried. Add "--no-dangling" option to omit them, and update the user manual to demonstrate its use. Based on a patch by Clemens Buchacher, but reverted the part to change the default to --no-dangling, which is unsuitable for the first patch. The usual three-step procedure to break the backward compatibility over time needs to happen on top of this, if we were to go in that direction. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-02-28 23:55:39 +01:00
view real errors.
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[recovering-lost-changes]]
user-manual: stub discussion of fsck and reflog Have some sort of recovery/reliability section that deals with reflog and fsck. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-26 06:17:12 +01:00
Recovering lost changes
~~~~~~~~~~~~~~~~~~~~~~~
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[reflogs]]
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
Reflogs
^^^^^^^
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>,
and then realize that the branch was the only reference you had to
that point in history.
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Fortunately, Git also keeps a log, called a "reflog", of all the
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
previous values of each branch. So in this case you can still find the
War on whitespace 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>
2007-06-07 09:04:01 +02:00
old history using, for example,
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
-------------------------------------------------
$ git log master@{1}
-------------------------------------------------
user-manual.txt: minor clarification. Signed-off-by: Sergei Organov <osv@javad.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-16 12:28:57 +01:00
This lists the commits reachable from the previous version of the
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`master` branch head. This syntax can be used with any Git command
that accepts a commit, not just with `git log`. Some other examples:
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
-------------------------------------------------
$ git show master@{2} # See where the branch pointed 2,
$ git show master@{3} # 3, ... changes ago.
$ gitk master@{yesterday} # See where it pointed yesterday,
$ gitk master@{"1 week ago"} # ... or last week
user-manual: more discussion of detached heads, fix typos 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>
2007-04-18 06:20:46 +02:00
$ git log --walk-reflogs master # show reflog entries for master
-------------------------------------------------
A separate reflog is kept for the HEAD, so
-------------------------------------------------
$ git show HEAD@{"1 week ago"}
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
-------------------------------------------------
user-manual: more discussion of detached heads, fix typos 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>
2007-04-18 06:20:46 +02:00
will show what HEAD pointed to one week ago, not what the current branch
pointed to one week ago. This allows you to see the history of what
you've checked out.
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
The reflogs are kept by default for 30 days, after which they may be
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
how to control this pruning, and see the "SPECIFYING REVISIONS"
Documentation: gitrevisions is in section 7 Fix references to gitrevisions(1) in the manual pages and HTML documentation. In practice, this will not matter much unless someone tries to use a hard copy of the git reference manual. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-11 18:03:32 +02:00
section of linkgit:gitrevisions[7] for details.
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Note that the reflog history is very different from normal Git history.
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
While normal history is shared by every repository that works on the
same project, the reflog history is not shared: it tells you only about
how the branches in your local repository have changed over time.
user-manual: clean up fast-forward and dangling-objects sections 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
2007-04-30 17:11:02 +02:00
[[dangling-object-recovery]]
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
Examining dangling objects
^^^^^^^^^^^^^^^^^^^^^^^^^^
user-manual: clean up fast-forward and dangling-objects sections 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
2007-04-30 17:11:02 +02:00
In some situations the reflog may not be able to save you. For example,
suppose you delete a branch, then realize you need the history it
contained. The reflog is also deleted; however, if you have not yet
pruned the repository, then you may still be able to find the lost
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
commits in the dangling objects that `git fsck` reports. See
user-manual: clean up fast-forward and dangling-objects sections 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
2007-04-30 17:11:02 +02:00
<<dangling-objects>> for the details.
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
-------------------------------------------------
$ git fsck
dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
...
-------------------------------------------------
Fix some documentation typos and grammar Also suggest user manual mention .gitignore. Signed-off-by: Michael Coleman <tutufan@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-02 07:25:30 +01:00
You can examine
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
one of those dangling commits with, for example,
------------------------------------------------
$ gitk 7281251ddd --not --all
------------------------------------------------
which does what it sounds like: it says that you want to see the commit
history that is described by the dangling commit(s), but not the
history that is described by all your existing branches and tags. Thus
you get exactly the history reachable from that commit that is lost.
(And notice that it might not be just one commit: we only report the
"tip of the line" as being dangling, but there might be a whole deep
Fix minor typos/grammar in user-manual.txt Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-28 05:13:09 +01:00
and complex commit history that was dropped.)
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
If you decide you want the history back, you can always create a new
reference pointing to it, for example, a new branch:
------------------------------------------------
War on whitespace 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>
2007-06-07 09:04:01 +02:00
$ git branch recovered-branch 7281251ddd
user-manual: reflogs, other recovery 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>
2007-01-29 07:31:35 +01:00
------------------------------------------------
user-manual: clean up fast-forward and dangling-objects sections 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
2007-04-30 17:11:02 +02:00
Other types of dangling objects (blobs and trees) are also possible, and
dangling objects can arise in other situations.
user-manual: stub discussion of fsck and reflog Have some sort of recovery/reliability section that deals with reflog and fsck. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-26 06:17:12 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[sharing-development]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Sharing development with others
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
===============================
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
work around Python warnings from AsciiDoc It appears that a reference to an anchor defined as [[anchor-name]] from another place using <<anchor-name>> syntax, when the anchor name contains a string "-with-" in its name, triggers these warnings from Python interpreter. asciidoc -b docbook -d book user-manual.txt <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 There currently is no reference to "Finding comments with given content", but for consistency and for futureproofing, the anchor is also updated as the other ones that are actually used and trigger these warnings. Signed-off-by: Junio C Hamano <junio@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-08 03:38:46 +01:00
[[getting-updates-With-git-pull]]
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Getting updates with git pull
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
-----------------------------
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Document that "git merge" doesn't like uncommited changes. We explain the user why uncommited changes can be problematic with merge, and point to "commit" and "stash" for the solution. While talking about commited Vs uncommited changes, we also make it clear that the result of a merge is normally commited. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-22 23:26:18 +01:00
After you clone a repository and commit a few changes of your own, you
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
may wish to check the original repository for updates and merge them
into your own work.
work around Python warnings from AsciiDoc It appears that a reference to an anchor defined as [[anchor-name]] from another place using <<anchor-name>> syntax, when the anchor name contains a string "-with-" in its name, triggers these warnings from Python interpreter. asciidoc -b docbook -d book user-manual.txt <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 There currently is no reference to "Finding comments with given content", but for consistency and for futureproofing, the anchor is also updated as the other ones that are actually used and trigger these warnings. Signed-off-by: Junio C Hamano <junio@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-08 03:38:46 +01:00
We have already seen <<Updating-a-repository-With-git-fetch,how to
Replace "remote tracking" with "remote-tracking" "remote-tracking" branch makes it explicit that the branch is "tracking a remote", as opposed to "remote, and tracking something". See discussion in e.g. http://mid.gmane.org/8835ADF9-45E5-4A26-9F7F-A72ECC065BB2@gmail.com for more details. This patch is a straightforward application of perl -pi -e 's/remote tracking branch/remote-tracking branch/' except in the RelNotes directory. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 16:31:20 +01:00
keep remote-tracking branches up to date>> with linkgit:git-fetch[1],
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
and how to merge two branches. So you can merge in changes from the
original repository's master branch with:
-------------------------------------------------
$ git fetch
$ git merge origin/master
-------------------------------------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
However, the linkgit:git-pull[1] command provides a way to do this in
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
one step:
-------------------------------------------------
$ git pull origin master
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
In fact, if you have `master` checked out, then this branch has been
configured by `git clone` to get changes from the HEAD branch of the
user-manual.txt: explain better the remote(-tracking) branch terms Now that the documentation is mostly consistant in the use of "remote branch" Vs "remote-tracking branch", let's make this distinction explicit early in the user-manual. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 22:06:20 +01:00
origin repository. So often you can
user-manual: update for new default --track behavior 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>
2007-08-05 23:18:52 +02:00
accomplish the above with just a simple
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git pull
-------------------------------------------------
user-manual.txt: explain better the remote(-tracking) branch terms Now that the documentation is mostly consistant in the use of "remote branch" Vs "remote-tracking branch", let's make this distinction explicit early in the user-manual. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 22:06:20 +01:00
This command will fetch changes from the remote branches to your
remote-tracking branches `origin/*`, and merge the default branch into
the current branch.
Change incorrect uses of "remote branch" meaning "remote-tracking" "remote branch" is a branch hosted in a remote repository, while "remote-tracking branch" is a copy of such branch, hosted locally. The distinction is subtle when the copy is up-to-date, but rather fundamental to understand what "git fetch" and "git push" do. This patch should fix all incorrect usages in Documentation/ directory. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 16:31:24 +01:00
More generally, a branch that is created from a remote-tracking branch
will pull
user-manual: update for new default --track behavior 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>
2007-08-05 23:18:52 +02:00
by default from that branch. See the descriptions of the
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`branch.<name>.remote` and `branch.<name>.merge` options in
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-config[1], and the discussion of the `--track` option in
linkgit:git-checkout[1], to learn how to control these defaults.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
In addition to saving you keystrokes, `git pull` also helps you by
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
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
Use 'fast-forward' all over the place It's a compound word. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-24 10:31:32 +02:00
<<fast-forwards,fast-forward>>; instead, your branch will just be
Fix minor typos/grammar in user-manual.txt Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-28 05:13:09 +01:00
updated to point to the latest commit from the upstream branch.)
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
The `git pull` command can also be given `.` as the "remote" repository,
user-manual: rewrap a few long lines Rewrap some long lines. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-29 07:33:55 +01:00
in which case it just merges in a branch from the current repository; so
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
the commands
-------------------------------------------------
$ git pull . branch
$ git merge branch
-------------------------------------------------
Use "git merge" instead of "git pull ." "git pull ." works, but "git merge" is the recommended way for new users to do things. (The old description also should have read "The former is actually *not* very commonly used".) Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:58:18 +02:00
are roughly equivalent.
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[submitting-patches]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Submitting patches to a project
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
-------------------------------
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
If you just have a few changes, the simplest way to submit them may
just be to send them as patches in email:
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
First, use linkgit:git-format-patch[1]; for example:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
User manual: fix typos in examples 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>
2007-01-11 03:11:53 +01:00
$ git format-patch origin
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
will produce a numbered series of files in the current directory, one
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
for each patch in the current branch but not in `origin/HEAD`.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Doc User-Manual: Patch cover letter, three dashes, and --notes Show that git format-patch can have a cover letter, include patch commentary below the three dashes, and notes can also be included. Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Jeff King <peff@peff.net>
2012-10-21 23:34:08 +02:00
`git format-patch` can include an initial "cover letter". You can insert
commentary on individual patches after the three dash line which
`format-patch` places after the commit message but before the patch
itself. If you use `git notes` to track your cover letter material,
`git format-patch --notes` will include the commit's notes in a similar
manner.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
You can then import these into your mail client and send them by
hand. However, if you have a lot to send at once, you may prefer to
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
use the linkgit:git-send-email[1] script to automate the process.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Consult the mailing list for your project first to determine how they
prefer such patches be handled.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[importing-patches]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Importing patches to a project
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
------------------------------
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
Git also provides a tool called linkgit:git-am[1] (am stands for
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
"apply mailbox"), for importing such an emailed series of patches.
Just save all of the patch-containing messages, in order, into a
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
single mailbox file, say `patches.mbox`, then run
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
User manual: fix typos in examples 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>
2007-01-11 03:11:53 +01:00
$ git am -3 patches.mbox
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
Git will apply each patch in order; if any conflicts are found, it
will stop, and you can fix the conflicts as described in
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
"<<resolving-a-merge,Resolving a merge>>". (The `-3` option tells
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Git to perform a merge; if you would prefer it just to abort and
user manual: answer some comments from Junio Junio left a few comments in his previous patch; deal with each of them. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-01-11 05:23:37 +01:00
leave your tree and index untouched, you may omit that option.)
Once the index is updated with the results of the conflict
resolution, instead of creating a new commit, just run
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
am: replace uses of --resolved with --continue git am was previously modified to provide --continue for consistency with rebase, merge etc, and the documentation changed to showing --continue as the primary form. Complete the work by replacing remaining uses of --resolved by --continue, most notably in suggested command reminders. Signed-off-by: Kevin Bracey <kevin@bracey.fi> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-26 22:06:41 +02:00
$ git am --continue
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
and Git will create the commit for you and continue applying the
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
remaining patches from the mailbox.
The final result will be a series of commits, one for each patch in
the original mailbox, with authorship and commit log message each
taken from the message containing each patch.
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
[[public-repositories]]
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Public Git repositories
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
-----------------------
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Documentation/user-manual.txt: fix a few omissions of gitlink commands. Signed-off-by: David Kastrup <dak@gnu.org>
2007-08-08 17:34:28 +02:00
Another way to submit changes to a project is to tell the maintainer
of that project to pull the changes from your repository using
work around Python warnings from AsciiDoc It appears that a reference to an anchor defined as [[anchor-name]] from another place using <<anchor-name>> syntax, when the anchor name contains a string "-with-" in its name, triggers these warnings from Python interpreter. asciidoc -b docbook -d book user-manual.txt <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 There currently is no reference to "Finding comments with given content", but for consistency and for futureproofing, the anchor is also updated as the other ones that are actually used and trigger these warnings. Signed-off-by: Junio C Hamano <junio@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-08 03:38:46 +01:00
linkgit:git-pull[1]. In the section "<<getting-updates-With-git-pull,
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Getting updates with `git pull`>>" we described this as a way to get
Documentation/user-manual.txt: fix a few omissions of gitlink commands. Signed-off-by: David Kastrup <dak@gnu.org>
2007-08-08 17:34:28 +02:00
updates from the "main" repository, but it works just as well in the
other direction.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
If you and the maintainer both have accounts on the same machine, then
you can just pull changes from each other's repositories directly;
user-manual: more explanation of push and pull usage 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>
2007-06-18 22:38:22 +02:00
commands that accept repository URLs as arguments will also accept a
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
local directory name:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git clone /path/to/repository
$ git pull /path/to/other/repository
-------------------------------------------------
manual: use 'URL' instead of 'url'. Just for consistency, use the spelling URL everywhere. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:03:55 +02:00
or an ssh URL:
user-manual: more explanation of push and pull usage 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>
2007-06-18 22:38:22 +02:00
-------------------------------------------------
$ git clone ssh://yourhost/~you/repository
-------------------------------------------------
For projects with few developers, or for synchronizing a few private
repositories, this may be all you need.
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
However, the more common way to do this is to maintain a separate public
repository (usually on a different host) for others to pull changes
from. This is usually more convenient, and allows you to cleanly
separate private work in progress from publicly visible work.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
You will continue to do your day-to-day work in your personal
repository, but periodically "push" changes from your personal
repository into your public repository, allowing other developers to
pull from that repository. So the flow of changes, in a situation
where there is one other developer with a public repository, looks
like this:
you push
your personal repo ------------------> your public repo
War on whitespace 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>
2007-06-07 09:04:01 +02:00
^ |
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
| |
| you pull | they pull
| |
| |
| they push V
their public repo <------------------- their repo
user-manual: more explanation of push and pull usage 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>
2007-06-18 22:38:22 +02:00
We explain how to do this in the following sections.
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
[[setting-up-a-public-repository]]
Setting up a public repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Assume your personal repository is in the directory `~/proj`. We
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
first create a new clone of the repository and tell `git daemon` that it
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
is meant to be public:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
user-manual: fix clone and fetch typos 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>
2007-05-08 05:34:26 +02:00
$ git clone --bare ~/proj proj.git
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
$ touch proj.git/git-daemon-export-ok
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
user-manual: fix clone and fetch typos 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>
2007-05-08 05:34:26 +02:00
The resulting directory proj.git contains a "bare" git repository--it is
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
just the contents of the `.git` directory, without any files checked out
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
around it.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Next, copy `proj.git` to the server where you plan to host the
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
public repository. You can use scp, rsync, or whatever is most
convenient.
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
[[exporting-via-git]]
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Exporting a Git repository via the Git protocol
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the preferred method.
If someone else administers the server, they should tell you what
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
directory to put the repository in, and what `git://` URL it will
appear at. You can then skip to the section
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
"<<pushing-changes-to-a-public-repository,Pushing changes to a public
repository>>", below.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
Otherwise, all you need to do is start linkgit:git-daemon[1]; it will
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
listen on port 9418. By default, it will allow access to any directory
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
that looks like a Git directory and contains the magic file
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
git-daemon-export-ok. Passing some directory paths as `git daemon`
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
arguments will further restrict the exports to those paths.
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
You can also run `git daemon` as an inetd service; see the
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-daemon[1] man page for details. (See especially the
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
examples section.)
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
[[exporting-via-http]]
user-manual: Fix 'http' -> 'HTTP' typos HTTP is an acronym which has not (yet) made the transition to word status (unlike "laser", probably because lasers are inherently cooler than HTTP ;). Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-10 16:10:37 +01:00
Exporting a git repository via HTTP
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
The Git protocol gives better performance and reliability, but on a
user-manual: Fix 'http' -> 'HTTP' typos HTTP is an acronym which has not (yet) made the transition to word status (unlike "laser", probably because lasers are inherently cooler than HTTP ;). Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-10 16:10:37 +01:00
host with a web server set up, HTTP exports may be simpler to set up.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
All you need to do is place the newly created bare Git repository in
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
a directory that is exported by the web server, and make some
adjustments to give web clients some extra information they need:
-------------------------------------------------
$ mv proj.git /home/you/public_html/proj.git
$ cd proj.git
user-manual: miscellaneous editing 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>
2007-05-07 06:56:45 +02:00
$ git --bare update-server-info
Adjust for the new way of enabling the default post-update hook The post-update hook, which is required to be enabled in order for the repository to be accessible over HTTP, is not enabled by chmod a+x anymore, but instead by dropping the .sample suffix. This patch emphasizes this change in the release notes (since I believe this is rather noticeable backwards-incompatible change). It also adjusts the documentation which still described the old way and fixes t/t5540-http-push.sh, which was broken for 1.5 month but apparently noone ever runs this test. Signed-off-by: Petr Baudis <pasky@suse.cz> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-08-12 00:34:46 +02:00
$ mv hooks/post-update.sample hooks/post-update
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
(For an explanation of the last two lines, see
Documentation: fix links to tutorials and other new manual pages With the conversion of HTML documentation to man pages tutorial.html -> gittutorial (7) tutorial-2.html -> gittutorial-2 (7) cvs-migration.html -> gitcvs-migration (7) diffcore.html -> gitdiffcore (7) repository-layout.html -> gitrepository-layout (5) hooks.html -> githooks (5) glossary.html -> gitglossary (7) core-tutorial.html -> gitcore-tutorial (7) and the automatic update of references to these pages, a little debris was left behind. We clear it away. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01 00:01:21 +02:00
linkgit:git-update-server-info[1] and linkgit:githooks[5].)
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Advertise the URL of `proj.git`. Anybody else should then be able to
manual: use 'URL' instead of 'url'. Just for consistency, use the spelling URL everywhere. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:03:55 +02:00
clone or pull from that URL, for example with a command line like:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git clone http://yourserver.com/~you/proj.git
-------------------------------------------------
(See also
Documentation: make AsciiDoc links always point to HTML files AsciiDoc's "link" is supposed to create hyperlinks for HTML output, so prefer a "link" to point to an HTML file instead of a text file if an HTML version of the file is being generated. For RelNotes, keep pointing to text files as no equivalent HTML files are generated. If appropriate, also update the link description to not contain the linked file's extension. Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-06 22:03:22 +02:00
link:howto/setup-git-server-over-http.html[setup-git-server-over-http]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
for a slightly more sophisticated setup using WebDAV which also
user-manual: Fix 'http' -> 'HTTP' typos HTTP is an acronym which has not (yet) made the transition to word status (unlike "laser", probably because lasers are inherently cooler than HTTP ;). Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-10 16:10:37 +01:00
allows pushing over HTTP.)
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
[[pushing-changes-to-a-public-repository]]
Pushing changes to a public repository
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
Note that the two techniques outlined above (exporting via
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
maintainers to fetch your latest changes, but they do not allow write
access, which you will need to update the public repository with the
latest changes created in your private repository.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The simplest way to do this is using linkgit:git-push[1] and ssh; to
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
update the remote branch named `master` with the latest state of your
branch named `master`, run
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git push ssh://yourserver.com/~you/proj.git master:master
-------------------------------------------------
or just
-------------------------------------------------
$ git push ssh://yourserver.com/~you/proj.git master
-------------------------------------------------
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
As with `git fetch`, `git push` will complain if this does not result in a
Use 'fast-forward' all over the place It's a compound word. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-24 10:31:32 +02:00
<<fast-forwards,fast-forward>>; see the following section for details on
user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 23:54:19 +01:00
handling this case.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Note that the target of a `push` is normally a
user-manual: more explanation of push and pull usage 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>
2007-06-18 22:38:22 +02:00
<<def_bare_repository,bare>> repository. You can also push to a
user-manual: Update for receive.denyCurrentBranch=refuse acd2a45 (Refuse updating the current branch in a non-bare repository via push, 2009-02-11) changed the default to refuse such a push, but it forgot to update the docs. 7d182f5 (Documentation: receive.denyCurrentBranch defaults to 'refuse', 2010-03-17) updated Documentation/config.txt, but forgot to update the user manual. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-08 18:04:20 +01:00
repository that has a checked-out working tree, but a push to update the
currently checked-out branch is denied by default to prevent confusion.
user-manual: typofix (ofthe->of the) Noticed by Drew Northup Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 21:43:00 +01:00
See the description of the receive.denyCurrentBranch option
user-manual: Update for receive.denyCurrentBranch=refuse acd2a45 (Refuse updating the current branch in a non-bare repository via push, 2009-02-11) changed the default to refuse such a push, but it forgot to update the docs. 7d182f5 (Documentation: receive.denyCurrentBranch defaults to 'refuse', 2010-03-17) updated Documentation/config.txt, but forgot to update the user manual. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-08 18:04:20 +01:00
in linkgit:git-config[1] for details.
user-manual: more explanation of push and pull usage 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>
2007-06-18 22:38:22 +02:00
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
As with `git fetch`, you may also set up configuration options to
user-manual: use 'remote add' to setup push URLs There is no need to use here documents to setup this configuration. It is easier, less confusing, and more robust to use `git remote add` directly. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:53 +01:00
save typing; so, for example:
-------------------------------------------------
$ git remote add public-repo ssh://yourserver.com/~you/proj.git
-------------------------------------------------
adds the following to `.git/config`:
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
[remote "public-repo"]
user-manual: use 'remote add' to setup push URLs There is no need to use here documents to setup this configuration. It is easier, less confusing, and more robust to use `git remote add` directly. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:53 +01:00
url = yourserver.com:proj.git
fetch = +refs/heads/*:refs/remotes/example/*
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
user-manual: use 'remote add' to setup push URLs There is no need to use here documents to setup this configuration. It is easier, less confusing, and more robust to use `git remote add` directly. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:53 +01:00
which lets you do the same push with just
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
-------------------------------------------------
$ git push public-repo master
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
See the explanations of the `remote.<name>.url`,
`branch.<name>.remote`, and `remote.<name>.push` options in
linkgit:git-config[1] for details.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 23:54:19 +01:00
[[forcing-push]]
What to do when a push fails
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use 'fast-forward' all over the place It's a compound word. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-24 10:31:32 +02:00
If a push would not result in a <<fast-forwards,fast-forward>> of the
user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 23:54:19 +01:00
remote branch, then it will fail with an error like:
-------------------------------------------------
error: remote 'refs/heads/master' is not an ancestor of
local 'refs/heads/master'.
Maybe you are not up-to-date and need to pull first?
error: failed to push to 'ssh://yourserver.com/~you/proj.git'
-------------------------------------------------
This can happen, for example, if you:
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
- use `git reset --hard` to remove already-published commits, or
- use `git commit --amend` to replace already-published commits
user-manual: clarify language about "modifying" old commits It's important to remember that git doesn't really allowing "editing" or "modifying" commits, only replacing them by new commits. Redo some of the language to make this clearer. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-26 01:01:57 +01:00
(as in <<fixing-a-mistake-by-rewriting-history>>), or
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
- use `git rebase` to rebase any already-published commits (as
user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 23:54:19 +01:00
in <<using-git-rebase>>).
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
You may force `git push` to perform the update anyway by preceding the
user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 23:54:19 +01:00
branch name with a plus sign:
-------------------------------------------------
$ git push ssh://yourserver.com/~you/proj.git +master
-------------------------------------------------
user-manual: give 'git push -f' as an alternative to +master This mirrors existing language in the description of 'git fetch'. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:55 +01:00
Note the addition of the `+` sign. Alternatively, you can use the
`-f` flag to force the remote update, as in:
-------------------------------------------------
$ git push -f ssh://yourserver.com/~you/proj.git master
-------------------------------------------------
user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 23:54:19 +01:00
Normally whenever a branch head in a public repository is modified, it
Fix spelling mistakes in user manual Signed-off-by: Shawn Bohrer <shawn.bohrer@gmail.com> Acked-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-13 05:36:21 +01:00
is modified to point to a descendant of the commit that it pointed to
user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 23:54:19 +01:00
before. By forcing a push in this situation, you break that convention.
work around Python warnings from AsciiDoc It appears that a reference to an anchor defined as [[anchor-name]] from another place using <<anchor-name>> syntax, when the anchor name contains a string "-with-" in its name, triggers these warnings from Python interpreter. asciidoc -b docbook -d book user-manual.txt <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 There currently is no reference to "Finding comments with given content", but for consistency and for futureproofing, the anchor is also updated as the other ones that are actually used and trigger these warnings. Signed-off-by: Junio C Hamano <junio@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-08 03:38:46 +01:00
(See <<problems-With-rewriting-history>>.)
user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 23:54:19 +01:00
Nevertheless, this is a common practice for people that need a simple
way to publish a work-in-progress patch series, and it is an acceptable
compromise as long as you warn other developers that this is how you
intend to manage the branch.
It's also possible for a push to fail in this way when other people have
the right to push to the same repository. In that case, the correct
user-manual: typo and grammar fixes Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-08 22:00:30 +02:00
solution is to retry the push after first updating your work: either by a
pull, or by a fetch followed by a rebase; see the
user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 23:54:19 +01:00
<<setting-up-a-shared-repository,next section>> and
Documentation: fix links to tutorials and other new manual pages With the conversion of HTML documentation to man pages tutorial.html -> gittutorial (7) tutorial-2.html -> gittutorial-2 (7) cvs-migration.html -> gitcvs-migration (7) diffcore.html -> gitdiffcore (7) repository-layout.html -> gitrepository-layout (5) hooks.html -> githooks (5) glossary.html -> gitglossary (7) core-tutorial.html -> gitcore-tutorial (7) and the automatic update of references to these pages, a little debris was left behind. We clear it away. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01 00:01:21 +02:00
linkgit:gitcvs-migration[7] for more.
user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-25 23:54:19 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[setting-up-a-shared-repository]]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Setting up a shared repository
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Another way to collaborate is by using a model similar to that
commonly used in CVS, where several developers with special rights
all push to and pull from a single shared repository. See
Documentation: fix links to tutorials and other new manual pages With the conversion of HTML documentation to man pages tutorial.html -> gittutorial (7) tutorial-2.html -> gittutorial-2 (7) cvs-migration.html -> gitcvs-migration (7) diffcore.html -> gitdiffcore (7) repository-layout.html -> gitrepository-layout (5) hooks.html -> githooks (5) glossary.html -> gitglossary (7) core-tutorial.html -> gitcore-tutorial (7) and the automatic update of references to these pages, a little debris was left behind. We clear it away. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01 00:01:21 +02:00
linkgit:gitcvs-migration[7] for instructions on how to
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
set this up.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
However, while there is nothing wrong with Git's support for shared
user-manual: discourage shared repository 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>
2007-05-15 06:30:58 +02:00
repositories, this mode of operation is not generally recommended,
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
simply because the mode of collaboration that Git supports--by
user-manual: discourage shared repository 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>
2007-05-15 06:30:58 +02:00
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
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
high rates. And when that becomes too much, `git pull` provides
user-manual: discourage shared repository 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>
2007-05-15 06:30:58 +02:00
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".
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[setting-up-gitweb]]
user-manual: reorganize public git repo discussion 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>
2007-05-15 06:00:29 +02:00
Allowing web browsing of a repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: point to README for gitweb information 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>
2007-01-30 18:43:36 +01:00
The gitweb cgi script provides users an easy way to browse your
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
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.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[sharing-development-examples]]
Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 05:42:36 +01:00
Examples
--------
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
[[maintaining-topic-branches]]
Maintaining topic branches for a Linux subsystem maintainer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
This describes how Tony Luck uses Git in his role as maintainer of the
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
IA64 architecture for the Linux kernel.
He uses two public branches:
- A "test" tree into which patches are initially placed so that they
can get some exposure when integrated with other ongoing development.
This tree is available to Andrew for pulling into -mm whenever he
wants.
- A "release" tree into which tested patches are moved for final sanity
checking, and as a vehicle to send them upstream to Linus (by sending
him a "please pull" request.)
He also uses a set of temporary branches ("topic branches"), each
containing a logical grouping of patches.
To set this up, first create your work tree by cloning Linus's public
tree:
-------------------------------------------------
Documentation: Update 'linux-2.6.git' -> 'linux.git' The 3.x tree has been out for a while now. The -2.6 repository name survived the initial release [1], but kernel.org now only lists 'linux.git' (for aegl as well as torvalds) [2]. [1]: http://article.gmane.org/gmane.linux.kernel/1147422 On 2011-05-30 01:47:57 GMT, Linus Torvalds wrote: > ... yes, that means that my git tree is still called > "linux-2.6.git" on kernel.org. [2]: http://git.kernel.org/cgit/ Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-22 16:46:27 +02:00
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
$ cd work
-------------------------------------------------
Change incorrect uses of "remote branch" meaning "remote-tracking" "remote branch" is a branch hosted in a remote repository, while "remote-tracking branch" is a copy of such branch, hosted locally. The distinction is subtle when the copy is up-to-date, but rather fundamental to understand what "git fetch" and "git push" do. This patch should fix all incorrect usages in Documentation/ directory. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 16:31:24 +01:00
Linus's tree will be stored in the remote-tracking branch named origin/master,
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
and can be updated using linkgit:git-fetch[1]; you can track other
public trees using linkgit:git-remote[1] to set up a "remote" and
linkgit:git-fetch[1] to keep them up-to-date; see
Documentation/user-manual.txt: fix a few omissions of gitlink commands. Signed-off-by: David Kastrup <dak@gnu.org>
2007-08-08 17:34:28 +02:00
<<repositories-and-branches>>.
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
Now create the branches in which you are going to work; these start out
at the current tip of origin/master branch, and should be set up (using
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
the `--track` option to linkgit:git-branch[1]) to merge changes in from
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
Linus by default.
-------------------------------------------------
$ git branch --track test origin/master
$ git branch --track release origin/master
-------------------------------------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
These can be easily kept up to date using linkgit:git-pull[1].
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
-------------------------------------------------
$ git checkout test && git pull
$ git checkout release && git pull
-------------------------------------------------
Important note! If you have any local changes in these branches, then
this merge will create a commit object in the history (with no local
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
changes Git will simply do a "fast-forward" merge). Many people dislike
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
the "noise" that this creates in the Linux history, so you should avoid
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
doing this capriciously in the `release` branch, as these noisy commits
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
will become part of the permanent history when you ask Linus to pull
from the release branch.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
A few configuration variables (see linkgit:git-config[1]) can
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
make it easy to push both branches to your public tree. (See
<<setting-up-a-public-repository>>.)
-------------------------------------------------
$ cat >> .git/config <<EOF
[remote "mytree"]
Documentation: Update 'linux-2.6.git' -> 'linux.git' The 3.x tree has been out for a while now. The -2.6 repository name survived the initial release [1], but kernel.org now only lists 'linux.git' (for aegl as well as torvalds) [2]. [1]: http://article.gmane.org/gmane.linux.kernel/1147422 On 2011-05-30 01:47:57 GMT, Linus Torvalds wrote: > ... yes, that means that my git tree is still called > "linux-2.6.git" on kernel.org. [2]: http://git.kernel.org/cgit/ Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-22 16:46:27 +02:00
url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
push = release
push = test
EOF
-------------------------------------------------
Then you can push both the test and release trees using
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-push[1]:
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
-------------------------------------------------
$ git push mytree
-------------------------------------------------
or push just one of the test and release branches using:
-------------------------------------------------
$ git push mytree test
-------------------------------------------------
or
-------------------------------------------------
$ git push mytree release
-------------------------------------------------
Now to apply some patches from the community. Think of a short
snappy name for a branch to hold this patch (or related group of
Better advice on using topic branches for kernel development Linus Torvalds wrote: > The real problem is that maintainers often pick random - and not at > all stable - points for their development to begin with. They just > pick some random "this is where Linus -git tree is today", and do > their development on top of that. THAT is the problem - they are > unaware that there's some nasty bug in that version. Maybe they do this because they read it in the Git user-manual. Fix the manual to give them better guidance. Signed-off-by: Tony Luck <tony.luck@intel.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-01 20:57:52 +02:00
patches), and create a new branch from a recent stable tag of
Linus's branch. Picking a stable base for your branch will:
1) help you: by avoiding inclusion of unrelated and perhaps lightly
tested changes
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
2) help future bug hunters that use `git bisect` to find problems
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
-------------------------------------------------
Better advice on using topic branches for kernel development Linus Torvalds wrote: > The real problem is that maintainers often pick random - and not at > all stable - points for their development to begin with. They just > pick some random "this is where Linus -git tree is today", and do > their development on top of that. THAT is the problem - they are > unaware that there's some nasty bug in that version. Maybe they do this because they read it in the Git user-manual. Fix the manual to give them better guidance. Signed-off-by: Tony Luck <tony.luck@intel.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-01 20:57:52 +02:00
$ git checkout -b speed-up-spinlocks v2.6.35
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
-------------------------------------------------
Now you apply the patch(es), run some tests, and commit the change(s). If
the patch is a multi-part series, then you should apply each as a separate
commit to this branch.
-------------------------------------------------
$ ... patch ... test ... commit [ ... patch ... test ... commit ]*
-------------------------------------------------
Use "git merge" instead of "git pull ." "git pull ." works, but "git merge" is the recommended way for new users to do things. (The old description also should have read "The former is actually *not* very commonly used".) Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:58:18 +02:00
When you are happy with the state of this change, you can merge it into the
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
"test" branch in preparation to make it public:
-------------------------------------------------
Use "git merge" instead of "git pull ." "git pull ." works, but "git merge" is the recommended way for new users to do things. (The old description also should have read "The former is actually *not* very commonly used".) Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:58:18 +02:00
$ git checkout test && git merge speed-up-spinlocks
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
-------------------------------------------------
It is unlikely that you would have any conflicts here ... but you might if you
spent a while on this step and had also pulled new versions from upstream.
Some time later when enough time has passed and testing done, you can pull the
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
same branch into the `release` tree ready to go upstream. This is where you
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
see the value of keeping each patch (or patch series) in its own branch. It
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
means that the patches can be moved into the `release` tree in any order.
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
-------------------------------------------------
Use "git merge" instead of "git pull ." "git pull ." works, but "git merge" is the recommended way for new users to do things. (The old description also should have read "The former is actually *not* very commonly used".) Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:58:18 +02:00
$ git checkout release && git merge speed-up-spinlocks
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
-------------------------------------------------
After a while, you will have a number of branches, and despite the
well chosen names you picked for each of them, you may forget what
they are for, or what status they are in. To get a reminder of what
changes are in a specific branch, use:
-------------------------------------------------
Documentation: more "git-" versus "git " changes With git-commands moving out of $(bindir), it is useful to make a clearer distinction between the git subcommand 'git-whatever' and the command you type, `git whatever <options>`. So we use a dash after "git" when referring to the former and not the latter. I already sent a patch doing this same thing, but I missed some spots. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-03 07:28:15 +02:00
$ git log linux..branchname | git shortlog
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
-------------------------------------------------
Fix some typos, punctuation, missing words, minor markup. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:00:03 +02:00
To see whether it has already been merged into the test or release branches,
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
use:
-------------------------------------------------
$ git log test..branchname
-------------------------------------------------
or
-------------------------------------------------
$ git log release..branchname
-------------------------------------------------
Fix some typos, punctuation, missing words, minor markup. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:00:03 +02:00
(If this branch has not yet been merged, you will see some log entries.
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
If it has been merged, then there will be no output.)
Once a patch completes the great cycle (moving from test to release,
then pulled by Linus, and finally coming back into your local
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`origin/master` branch), the branch for this change is no longer needed.
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
You detect this when the output from:
-------------------------------------------------
$ git log origin..branchname
-------------------------------------------------
is empty. At this point the branch can be deleted:
-------------------------------------------------
$ git branch -d branchname
-------------------------------------------------
Some changes are so trivial that it is not necessary to create a separate
branch and then merge into each of the test and release branches. For
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
these changes, just apply directly to the `release` branch, and then
merge that into the `test` branch.
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
user-manual: Use request-pull to generate "please pull" text Less work and more error checking (e.g. does a merge base exist?). Add an explicit push before request-pull to satisfy request-pull, which checks to make sure the references are publically available. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:01 +01:00
After pushing your work to `mytree`, you can use
linkgit:git-request-pull[1] to prepare a "please pull" request message
to send to Linus:
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
-------------------------------------------------
user-manual: Use request-pull to generate "please pull" text Less work and more error checking (e.g. does a merge base exist?). Add an explicit push before request-pull to satisfy request-pull, which checks to make sure the references are publically available. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:01 +01:00
$ git push mytree
$ git request-pull origin mytree release
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
-------------------------------------------------
Here are some of the scripts that simplify all this even further.
-------------------------------------------------
==== update script ====
Documentation: avoid poor-man's small caps GIT In the earlier days, we used to spell the name of the system as GIT, to simulate as if it were typeset with capital G and IT in small caps. Later we stopped doing so at around 1.6.5 days. Let's stop doing so throughout the documentation. The name to refer to the whole system (and the concept it embodies) is "Git"; the command end-users type is "git". And document this in the coding guideline. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:16:20 +01:00
# Update a branch in my Git tree. If the branch to be updated
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
# is origin, then pull from kernel.org. Otherwise merge
# origin/master branch into test|release branch
case "$1" in
test|release)
git checkout $1 && git pull . origin
;;
origin)
user-manual: don't assume refs are stored under .git/refs The scripts taken from Tony Luck's howto assume all refs can be found under .git/refs, but this is not necessarily true, especially since git-gc runs git-pack-refs. Also add a note warning of this in the chapter that introduces refs, and fix the same incorrect assumption in one other spot. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-10 04:07:02 +02:00
before=$(git rev-parse refs/remotes/origin/master)
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
git fetch origin
user-manual: don't assume refs are stored under .git/refs The scripts taken from Tony Luck's howto assume all refs can be found under .git/refs, but this is not necessarily true, especially since git-gc runs git-pack-refs. Also add a note warning of this in the chapter that introduces refs, and fix the same incorrect assumption in one other spot. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-10 04:07:02 +02:00
after=$(git rev-parse refs/remotes/origin/master)
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
if [ $before != $after ]
then
git log $before..$after | git shortlog
fi
;;
*)
Documentation/user-manual.txt: use a lowercase "usage:" string Make the usage string in the example script consistent with Git. Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: David Aguilar <davvid@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-24 01:50:24 +01:00
echo "usage: $0 origin|test|release" 1>&2
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
exit 1
;;
esac
-------------------------------------------------
-------------------------------------------------
==== merge script ====
# Merge a branch into either the test or release branch
pname=$0
usage()
{
Documentation/user-manual.txt: use a lowercase "usage:" string Make the usage string in the example script consistent with Git. Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: David Aguilar <davvid@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-24 01:50:24 +01:00
echo "usage: $pname branch test|release" 1>&2
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
exit 1
}
user-manual: don't assume refs are stored under .git/refs The scripts taken from Tony Luck's howto assume all refs can be found under .git/refs, but this is not necessarily true, especially since git-gc runs git-pack-refs. Also add a note warning of this in the chapter that introduces refs, and fix the same incorrect assumption in one other spot. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-10 04:07:02 +02:00
git show-ref -q --verify -- refs/heads/"$1" || {
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
echo "Can't see branch <$1>" 1>&2
usage
user-manual: don't assume refs are stored under .git/refs The scripts taken from Tony Luck's howto assume all refs can be found under .git/refs, but this is not necessarily true, especially since git-gc runs git-pack-refs. Also add a note warning of this in the chapter that introduces refs, and fix the same incorrect assumption in one other spot. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-10 04:07:02 +02:00
}
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
case "$2" in
test|release)
if [ $(git log $2..$1 | wc -c) -eq 0 ]
then
echo $1 already merged into $2 1>&2
exit 1
fi
git checkout $2 && git pull . $1
;;
*)
usage
;;
esac
-------------------------------------------------
-------------------------------------------------
==== status script ====
Documentation: avoid poor-man's small caps GIT In the earlier days, we used to spell the name of the system as GIT, to simulate as if it were typeset with capital G and IT in small caps. Later we stopped doing so at around 1.6.5 days. Let's stop doing so throughout the documentation. The name to refer to the whole system (and the concept it embodies) is "Git"; the command end-users type is "git". And document this in the coding guideline. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:16:20 +01:00
# report on status of my ia64 Git tree
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
gb=$(tput setab 2)
rb=$(tput setab 1)
restore=$(tput setab 9)
if [ `git rev-list test..release | wc -c` -gt 0 ]
then
echo $rb Warning: commits in release that are not in test $restore
git log test..release
fi
user-manual: don't assume refs are stored under .git/refs The scripts taken from Tony Luck's howto assume all refs can be found under .git/refs, but this is not necessarily true, especially since git-gc runs git-pack-refs. Also add a note warning of this in the chapter that introduces refs, and fix the same incorrect assumption in one other spot. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-10 04:07:02 +02:00
for branch in `git show-ref --heads | sed 's|^.*/||'`
user-manual: move howto/using-topic-branches into manual 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>
2007-05-13 07:48:47 +02:00
do
if [ $branch = test -o $branch = release ]
then
continue
fi
echo -n $gb ======= $branch ====== $restore " "
status=
for ref in test release origin/master
do
if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]
then
status=$status${ref:0:1}
fi
done
case $status in
trl)
echo $rb Need to pull into test $restore
;;
rl)
echo "In test"
;;
l)
echo "Waiting for linus"
;;
"")
echo $rb All done $restore
;;
*)
echo $rb "<$status>" $restore
;;
esac
git log origin/master..$branch | git shortlog
done
-------------------------------------------------
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
[[cleaning-up-history]]
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
Rewriting history and maintaining patch series
==============================================
Normally commits are only added to a project, never taken away or
replaced. Git is designed with this assumption, and violating it will
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
cause Git's merge machinery (for example) to do the wrong thing.
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
However, there is a situation in which it can be useful to violate this
assumption.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[patch-series]]
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
Creating the perfect patch series
---------------------------------
Suppose you are a contributor to a large project, and you want to add a
complicated feature, and to present it to the other developers in a way
that makes it easy for them to read your changes, verify that they are
correct, and understand why you made each change.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
If you present all of your changes as a single patch (or commit), they
Fix minor typos/grammar in user-manual.txt Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-28 05:13:09 +01:00
may find that it is too much to digest all at once.
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
If you present them with the entire history of your work, complete with
mistakes, corrections, and dead ends, they may be overwhelmed.
So the ideal is usually to produce a series of patches such that:
1. Each patch can be applied in order.
2. Each patch includes a single logical change, together with a
message explaining the change.
3. No patch introduces a regression: after applying any initial
part of the series, the resulting project still compiles and
works, and has no bugs that it didn't have before.
4. The complete series produces the same end result as your own
(probably much messier!) development process did.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
We will introduce some tools that can help you do this, explain how to
use them, and then explain some of the problems that can arise because
you are rewriting history.
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[using-git-rebase]]
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Keeping a patch series up to date using git rebase
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
--------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Suppose that you create a branch `mywork` on a remote-tracking branch
`origin`, and create some commits on top of it:
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
-------------------------------------------------
$ git checkout -b mywork origin
$ vi file.txt
$ git commit
$ vi otherfile.txt
$ git commit
...
-------------------------------------------------
You have performed no merges into mywork, so it is just a simple linear
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
sequence of patches on top of `origin`:
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: be consistent in illustrations to 'git rebase' Since we use a-b-c for mywork commits in one place, I think it would be logical to also use a-b-c too in other illustration on this topic. Signed-off-by: Kirill Smelkov <kirr@mns.spb.ru> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-09-28 10:20:24 +02:00
o--o--O <-- origin
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
\
user-manual: be consistent in illustrations to 'git rebase' Since we use a-b-c for mywork commits in one place, I think it would be logical to also use a-b-c too in other illustration on this topic. Signed-off-by: Kirill Smelkov <kirr@mns.spb.ru> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-09-28 10:20:24 +02:00
a--b--c <-- mywork
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
Some more interesting work has been done in the upstream project, and
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`origin` has advanced:
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
o--o--O--o--o--o <-- origin
\
a--b--c <-- mywork
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
At this point, you could use `pull` to merge your changes back in;
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
the result would create a new merge commit, like this:
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
o--o--O--o--o--o <-- origin
\ \
a--b--c--m <-- mywork
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
War on whitespace 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>
2007-06-07 09:04:01 +02:00
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
However, if you prefer to keep the history in mywork a simple series of
commits without any merges, you may instead choose to use
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-rebase[1]:
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
-------------------------------------------------
$ git checkout mywork
$ git rebase origin
-------------------------------------------------
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
This will remove each of your commits from mywork, temporarily saving
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
them as patches (in a directory named `.git/rebase-apply`), update mywork to
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
point at the latest version of origin, then apply each of the saved
patches to the new mywork. The result will look like:
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
o--o--O--o--o--o <-- origin
\
a'--b'--c' <-- mywork
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
In the process, it may discover conflicts. In that case it will stop
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
and allow you to fix the conflicts; after fixing conflicts, use `git add`
Documentation: rewrap to prepare for "git-" vs "git " change Rewrap lines in preparation for added dashes. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-03 07:20:21 +02:00
to update the index with those contents, and then, instead of
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
running `git commit`, just run
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
-------------------------------------------------
$ git rebase --continue
-------------------------------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
and Git will continue applying the rest of the patches.
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
manual: add some markup. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:03:11 +02:00
At any point you may use the `--abort` option to abort this process and
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
return mywork to the state it had before you started the rebase:
-------------------------------------------------
$ git rebase --abort
-------------------------------------------------
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
If you need to reorder or edit a number of commits in a branch, it may
be easier to use `git rebase -i`, which allows you to reorder and
squash commits, as well as marking them for individual editing during
the rebase. See <<interactive-rebase>> for details, and
<<reordering-patch-series>> for alternatives.
user-manual: clarify language about "modifying" old commits It's important to remember that git doesn't really allowing "editing" or "modifying" commits, only replacing them by new commits. Redo some of the language to make this clearer. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-26 01:01:57 +01:00
[[rewriting-one-commit]]
Rewriting a single commit
user-manual: how to replace commits older than most recent "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>
2007-03-03 20:30:32 +01:00
-------------------------
user-manual: clarify language about "modifying" old commits It's important to remember that git doesn't really allowing "editing" or "modifying" commits, only replacing them by new commits. Redo some of the language to make this clearer. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-26 01:01:57 +01:00
We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the
user-manual: how to replace commits older than most recent "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>
2007-03-03 20:30:32 +01:00
most recent commit using
-------------------------------------------------
$ git commit --amend
-------------------------------------------------
which will replace the old commit by a new commit incorporating your
changes, giving you a chance to edit the old commit message first.
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
This is useful for fixing typos in your last commit, or for adjusting
the patch contents of a poorly staged commit.
user-manual: how to replace commits older than most recent "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>
2007-03-03 20:30:32 +01:00
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
If you need to amend commits from deeper in your history, you can
use <<interactive-rebase,interactive rebase's `edit` instruction>>.
user-manual: how to replace commits older than most recent "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>
2007-03-03 20:30:32 +01:00
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
[[reordering-patch-series]]
Reordering or selecting from a patch series
-------------------------------------------
user-manual: how to replace commits older than most recent "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>
2007-03-03 20:30:32 +01:00
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
Sometimes you want to edit a commit deeper in your history. One
approach is to use `git format-patch` to create a series of patches
and then reset the state to before the patches:
user-manual: how to replace commits older than most recent "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>
2007-03-03 20:30:32 +01:00
-------------------------------------------------
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
$ git format-patch origin
$ git reset --hard origin
user-manual: how to replace commits older than most recent "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>
2007-03-03 20:30:32 +01:00
-------------------------------------------------
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
Then modify, reorder, or eliminate patches as needed before applying
them again with linkgit:git-am[1]:
user-manual: how to replace commits older than most recent "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>
2007-03-03 20:30:32 +01:00
-------------------------------------------------
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
$ git am *.patch
user-manual: how to replace commits older than most recent "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>
2007-03-03 20:30:32 +01:00
-------------------------------------------------
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
[[interactive-rebase]]
Using interactive rebases
-------------------------
user-manual: how to replace commits older than most recent "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>
2007-03-03 20:30:32 +01:00
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
You can also edit a patch series with an interactive rebase. This is
the same as <<reordering-patch-series,reordering a patch series using
`format-patch`>>, so use whichever interface you like best.
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
Rebase your current HEAD on the last commit you want to retain as-is.
For example, if you want to reorder the last 5 commits, use:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
$ git rebase -i HEAD~5
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
This will open your editor with a list of steps to be taken to perform
your rebase.
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
pick deadbee The oneline of this commit
pick fa1afe1 The oneline of the next commit
...
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: Reorganize the reroll sections, adding 'git rebase -i' I think this interface is often more convenient than extended cherry picking or using 'git format-patch'. In fact, I removed the cherry-pick section entirely. The entry-level suggestions for rerolling are now: 1. git commit --amend 2. git format-patch origin git reset --hard origin ...edit and reorder patches... git am *.patch 3. git rebase -i origin Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:00 +01:00
# Rebase c0ffeee..deadbee onto c0ffeee
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
-------------------------------------------------
As explained in the comments, you can reorder commits, squash them
together, edit commit messages, etc. by editing the list. Once you
are satisfied, save the list and close your editor, and the rebase
will begin.
The rebase will stop where `pick` has been replaced with `edit` or
when a step in the list fails to mechanically resolve conflicts and
needs your help. When you are done editing and/or resolving conflicts
you can continue with `git rebase --continue`. If you decide that
things are getting too hairy, you can always bail out with `git rebase
--abort`. Even after the rebase is complete, you can still recover
the original branch by using the <<reflogs,reflog>>.
For a more detailed discussion of the procedure and additional tips,
see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[patch-series-tools]]
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
Other tools
-----------
User Manual: Write "Git" instead of "GIT" In the Table of Contents, there is a notable inconsistency: first there is "GIT Glossary", followed by "Git Quick Reference" on the very next line. Running "grep -c" on user-manual.txt, I find 780 occurrrences of "git", 37 occurrences of "Git", and 9 occurrences of "GIT". In general, "git" is the preferred spelling, except at the beginning of a sentence. Therefore, change "GIT Glossary" to "Git Glossary" for consistency with the rest of the document. Looking at the other eight occurrences of "GIT" I found one other occurrence that should be changed: * The mention of "StGIT". Looking at the web pages for "Stacked Git" at http://www.procode.org/stgit, I only saw the spelling "StGit", except in http://wiki.procode.org/cgi-bin/wiki.cgi/StGIT_Tutorial, but that page was last updated in 2006. The other seven occurrences should not be changed: * Three occurrences were in the output of 'git show-branch' run on the git.git repository. * One occurrence was in the output of 'git cat-file'. * One occurrence was as part of the file name "GIT-VERSION-GEN". * Two occurrences were in comments in scripts quoted in a description of Tony Luck's workflow. Signed-off-by: Björn Gustavsson <bgustavsson@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-22 10:47:04 +01:00
There are numerous other tools, such as StGit, which exist for the
Fix minor typos/grammar in user-manual.txt Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-28 05:13:09 +01:00
purpose of maintaining a patch series. These are outside of the scope of
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
this manual.
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
work around Python warnings from AsciiDoc It appears that a reference to an anchor defined as [[anchor-name]] from another place using <<anchor-name>> syntax, when the anchor name contains a string "-with-" in its name, triggers these warnings from Python interpreter. asciidoc -b docbook -d book user-manual.txt <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 <string>:1: Warning: 'with' will become a reserved keyword in Python 2.6 There currently is no reference to "Finding comments with given content", but for consistency and for futureproofing, the anchor is also updated as the other ones that are actually used and trigger these warnings. Signed-off-by: Junio C Hamano <junio@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-08 03:38:46 +01:00
[[problems-With-rewriting-history]]
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
Problems with rewriting history
-------------------------------
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
The primary problem with rewriting the history of a branch has to do
with merging. Suppose somebody fetches your branch and merges it into
their branch, with a result something like this:
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
o--o--O--o--o--o <-- origin
\ \
t--t--t--m <-- their branch:
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Then suppose you modify the last three commits:
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
o--o--o <-- new head of origin
/
o--o--O--o--o--o <-- old head of origin
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
If we examined all this history together in one repository, it will
look like:
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
o--o--o <-- new head of origin
/
o--o--O--o--o--o <-- old head of origin
\ \
t--t--t--m <-- their branch:
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Git has no way of knowing that the new head is an updated version of
the old head; it treats this situation exactly the same as it would if
two developers had independently done the work on the old and new heads
in parallel. At this point, if someone attempts to merge the new head
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
in to their branch, Git will attempt to merge together the two (old and
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
new) lines of development, instead of trying to replace the old by the
new. The results are likely to be unexpected.
You may still choose to publish branches whose history is rewritten,
and it may be useful for others to be able to fetch those branches in
order to examine or test them, but they should not attempt to pull such
branches into their own work.
For true distributed development that supports proper merging,
published branches should never be rewritten.
user-manual: Add section "Why bisecting merge commits can be harder ..." This commit adds a discussion of the challenge of bisecting merge commits to the user manual. The original author is Junio C Hamano <gitster@pobox.com>, who posted the text to the mailing list <http://marc.info/?l=git&m=119403257315527&w=2>. His email was adapted for the manual. The discussion is added to "Rewriting history and maintainig patch series". The text added requires good understanding of merging and rebasing. Therefore it should not be placed too early in the manual. Right after the section on "Problems with rewriting history", the discussion of bisect gives another reason for linearizing as much of the history as possible. The text includes suggestions and fixes by Ralf Wildenhues <Ralf.Wildenhues@gmx.de> and Benoit Sigoure <tsuna@lrde.epita.fr>. Signed-off-by: Steffen Prohaska <prohaska@zib.de> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-10 14:49:54 +01:00
[[bisect-merges]]
Why bisecting merge commits can be harder than bisecting linear history
-----------------------------------------------------------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-bisect[1] command correctly handles history that
user-manual: Add section "Why bisecting merge commits can be harder ..." This commit adds a discussion of the challenge of bisecting merge commits to the user manual. The original author is Junio C Hamano <gitster@pobox.com>, who posted the text to the mailing list <http://marc.info/?l=git&m=119403257315527&w=2>. His email was adapted for the manual. The discussion is added to "Rewriting history and maintainig patch series". The text added requires good understanding of merging and rebasing. Therefore it should not be placed too early in the manual. Right after the section on "Problems with rewriting history", the discussion of bisect gives another reason for linearizing as much of the history as possible. The text includes suggestions and fixes by Ralf Wildenhues <Ralf.Wildenhues@gmx.de> and Benoit Sigoure <tsuna@lrde.epita.fr>. Signed-off-by: Steffen Prohaska <prohaska@zib.de> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-10 14:49:54 +01:00
includes merge commits. However, when the commit that it finds is a
merge commit, the user may need to work harder than usual to figure out
why that commit introduced a problem.
Imagine this history:
................................................
---Z---o---X---...---o---A---C---D
\ /
o---o---Y---...---o---B
................................................
Suppose that on the upper line of development, the meaning of one
of the functions that exists at Z is changed at commit X. The
commits from Z leading to A change both the function's
implementation and all calling sites that exist at Z, as well
as new calling sites they add, to be consistent. There is no
bug at A.
Suppose that in the meantime on the lower line of development somebody
adds a new calling site for that function at commit Y. The
commits from Z leading to B all assume the old semantics of that
function and the callers and the callee are consistent with each
other. There is no bug at B, either.
Suppose further that the two development lines merge cleanly at C,
so no conflict resolution is required.
Nevertheless, the code at C is broken, because the callers added
on the lower line of development have not been converted to the new
semantics introduced on the upper line of development. So if all
you know is that D is bad, that Z is good, and that
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-bisect[1] identifies C as the culprit, how will you
user-manual: Add section "Why bisecting merge commits can be harder ..." This commit adds a discussion of the challenge of bisecting merge commits to the user manual. The original author is Junio C Hamano <gitster@pobox.com>, who posted the text to the mailing list <http://marc.info/?l=git&m=119403257315527&w=2>. His email was adapted for the manual. The discussion is added to "Rewriting history and maintainig patch series". The text added requires good understanding of merging and rebasing. Therefore it should not be placed too early in the manual. Right after the section on "Problems with rewriting history", the discussion of bisect gives another reason for linearizing as much of the history as possible. The text includes suggestions and fixes by Ralf Wildenhues <Ralf.Wildenhues@gmx.de> and Benoit Sigoure <tsuna@lrde.epita.fr>. Signed-off-by: Steffen Prohaska <prohaska@zib.de> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-10 14:49:54 +01:00
figure out that the problem is due to this change in semantics?
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
When the result of a `git bisect` is a non-merge commit, you should
user-manual: Add section "Why bisecting merge commits can be harder ..." This commit adds a discussion of the challenge of bisecting merge commits to the user manual. The original author is Junio C Hamano <gitster@pobox.com>, who posted the text to the mailing list <http://marc.info/?l=git&m=119403257315527&w=2>. His email was adapted for the manual. The discussion is added to "Rewriting history and maintainig patch series". The text added requires good understanding of merging and rebasing. Therefore it should not be placed too early in the manual. Right after the section on "Problems with rewriting history", the discussion of bisect gives another reason for linearizing as much of the history as possible. The text includes suggestions and fixes by Ralf Wildenhues <Ralf.Wildenhues@gmx.de> and Benoit Sigoure <tsuna@lrde.epita.fr>. Signed-off-by: Steffen Prohaska <prohaska@zib.de> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-10 14:49:54 +01:00
normally be able to discover the problem by examining just that commit.
Developers can make this easy by breaking their changes into small
self-contained commits. That won't help in the case above, however,
because the problem isn't obvious from examination of any single
commit; instead, a global view of the development is required. To
make matters worse, the change in semantics in the problematic
function may be just one small part of the changes in the upper
line of development.
On the other hand, if instead of merging at C you had rebased the
history between Z to B on top of A, you would have gotten this
linear history:
................................................................
---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D*
................................................................
Bisecting between Z and D* would hit a single culprit commit Y*,
and understanding why Y* was broken would probably be easier.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Partly for this reason, many experienced Git users, even when
user-manual: Add section "Why bisecting merge commits can be harder ..." This commit adds a discussion of the challenge of bisecting merge commits to the user manual. The original author is Junio C Hamano <gitster@pobox.com>, who posted the text to the mailing list <http://marc.info/?l=git&m=119403257315527&w=2>. His email was adapted for the manual. The discussion is added to "Rewriting history and maintainig patch series". The text added requires good understanding of merging and rebasing. Therefore it should not be placed too early in the manual. Right after the section on "Problems with rewriting history", the discussion of bisect gives another reason for linearizing as much of the history as possible. The text includes suggestions and fixes by Ralf Wildenhues <Ralf.Wildenhues@gmx.de> and Benoit Sigoure <tsuna@lrde.epita.fr>. Signed-off-by: Steffen Prohaska <prohaska@zib.de> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-11-10 14:49:54 +01:00
working on an otherwise merge-heavy project, keep the history
linear by rebasing against the latest upstream version before
publishing.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[advanced-branch-management]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Advanced branch management
==========================
Documentation: git-rebase discussion, miscellaneous user-manual updates 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>
2007-01-08 05:57:41 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[fetching-individual-branches]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Fetching individual branches
----------------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
Instead of using linkgit:git-remote[1], you can also choose just
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
to update one branch at a time, and to store it locally under an
arbitrary name:
-------------------------------------------------
$ git fetch origin todo:my-todo-work
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
The first argument, `origin`, just tells Git to fetch from the
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
repository you originally cloned from. The second argument tells Git
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
to fetch the branch named `todo` from the remote repository, and to
store it locally under the name `refs/heads/my-todo-work`.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
You can also fetch branches from other repositories; so
-------------------------------------------------
$ git fetch git://example.com/proj.git master:example-master
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
will create a new branch named `example-master` and store in it the
branch named `master` from the repository at the given URL. If you
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
already have a branch named example-master, it will attempt to
user-manual: clean up fast-forward and dangling-objects sections 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
2007-04-30 17:11:02 +02:00
<<fast-forwards,fast-forward>> to the commit given by example.com's
master branch. In more detail:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: clean up fast-forward and dangling-objects sections 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
2007-04-30 17:11:02 +02:00
[[fetch-fast-forwards]]
git fetch and fast-forwards
---------------------------
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
In the previous example, when updating an existing branch, `git fetch`
Documentation: rewrap to prepare for "git-" vs "git " change Rewrap lines in preparation for added dashes. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-03 07:20:21 +02:00
checks to make sure that the most recent commit on the remote
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
branch is a descendant of the most recent commit on your copy of the
branch before updating your copy of the branch to point at the new
Use 'fast-forward' all over the place It's a compound word. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-24 10:31:32 +02:00
commit. Git calls this process a <<fast-forwards,fast-forward>>.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Use 'fast-forward' all over the place It's a compound word. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-24 10:31:32 +02:00
A fast-forward looks something like this:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
o--o--o--o <-- old head of the branch
\
o--o--o <-- new head of the branch
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
In some cases it is possible that the new head will *not* actually be
a descendant of the old head. For example, the developer may have
realized she made a serious mistake, and decided to backtrack,
resulting in a situation like:
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
o--o--o--o--a--b <-- old head of the branch
\
o--o--o <-- new head of the branch
user-manual: fix rendering of history diagrams 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>
2007-03-11 04:38:13 +01:00
................................................
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
In this case, `git fetch` will fail, and print out a warning.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
In that case, you can still force Git to update to the new head, as
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
described in the following section. However, note that in the
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
situation above this may mean losing the commits labeled `a` and `b`,
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
unless you've already created a reference of your own pointing to
them.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[forcing-fetch]]
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Forcing git fetch to do non-fast-forward updates
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
------------------------------------------------
If git fetch fails because the new head of a branch is not a
descendant of the old head, you may force the update with:
-------------------------------------------------
$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
-------------------------------------------------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Note the addition of the `+` sign. Alternatively, you can use the `-f`
user-manual: miscellaneous editing 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>
2007-05-07 06:56:45 +02:00
flag to force updates of all the fetched branches, as in:
-------------------------------------------------
$ git fetch -f origin
-------------------------------------------------
Be aware that commits that the old version of example/master pointed at
may be lost, as we saw in the previous section.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[remote-branch-configuration]]
Change incorrect uses of "remote branch" meaning "remote-tracking" "remote branch" is a branch hosted in a remote repository, while "remote-tracking branch" is a copy of such branch, hosted locally. The distinction is subtle when the copy is up-to-date, but rather fundamental to understand what "git fetch" and "git push" do. This patch should fix all incorrect usages in Documentation/ directory. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-02 16:31:24 +01:00
Configuring remote-tracking branches
------------------------------------
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
We saw above that `origin` is just a shortcut to refer to the
Fix minor typos/grammar in user-manual.txt Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-28 05:13:09 +01:00
repository that you originally cloned from. This information is
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
stored in Git configuration variables, which you can see using
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-config[1]:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: repo-config -> config 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>
2007-01-29 05:50:22 +01:00
$ git config -l
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
core.repositoryformatversion=0
core.filemode=true
core.logallrefupdates=true
remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.master.remote=origin
branch.master.merge=refs/heads/master
-------------------------------------------------
If there are other repositories that you also use frequently, you can
create similar configuration options to save typing; for example,
-------------------------------------------------
user-manual: mention 'git remote add' for remote branch config I hardly ever setup remote.<name>.url using 'git config'. While it may be instructive to do so, we should also point out 'git remote add'. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:56 +01:00
$ git remote add example git://example.com/proj.git
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: mention 'git remote add' for remote branch config I hardly ever setup remote.<name>.url using 'git config'. While it may be instructive to do so, we should also point out 'git remote add'. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:56 +01:00
adds the following to `.git/config`:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: mention 'git remote add' for remote branch config I hardly ever setup remote.<name>.url using 'git config'. While it may be instructive to do so, we should also point out 'git remote add'. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:56 +01:00
[remote "example"]
url = git://example.com/proj.git
fetch = +refs/heads/*:refs/remotes/example/*
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: mention 'git remote add' for remote branch config I hardly ever setup remote.<name>.url using 'git config'. While it may be instructive to do so, we should also point out 'git remote add'. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:56 +01:00
Also note that the above configuration can be performed by directly
editing the file `.git/config` instead of using linkgit:git-remote[1].
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: mention 'git remote add' for remote branch config I hardly ever setup remote.<name>.url using 'git config'. While it may be instructive to do so, we should also point out 'git remote add'. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:56 +01:00
After configuring the remote, the following three commands will do the
same thing:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: mention 'git remote add' for remote branch config I hardly ever setup remote.<name>.url using 'git config'. While it may be instructive to do so, we should also point out 'git remote add'. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:56 +01:00
$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/*
$ git fetch example +refs/heads/*:refs/remotes/example/*
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
$ git fetch example
-------------------------------------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
See linkgit:git-config[1] for more details on the configuration
user-manual: mention 'git remote add' for remote branch config I hardly ever setup remote.<name>.url using 'git config'. While it may be instructive to do so, we should also point out 'git remote add'. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-18 01:15:56 +01:00
options mentioned above and linkgit:git-fetch[1] for more details on
the refspec syntax.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: rename "git internals" to "git concepts" "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>
2007-08-31 05:10:05 +02:00
[[git-concepts]]
Git concepts
============
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: rename "git internals" to "git concepts" "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>
2007-08-31 05:10:05 +02:00
Git is built on a small number of simple but powerful ideas. While it
is possible to get things done without understanding them, you will find
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Git much more intuitive if you do.
user-manual: rename "git internals" to "git concepts" "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>
2007-08-31 05:10:05 +02:00
We start with the most important, the <<def_object_database,object
database>> and the <<def_index,index>>.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[the-object-database]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
The Object Database
-------------------
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
We already saw in <<understanding-commits>> that all commits are stored
under a 40-digit "object name". In fact, all the information needed to
represent the history of a project is stored in objects with such names.
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
In each case the name is calculated by taking the SHA-1 hash of the
contents of the object. The SHA-1 hash is a cryptographic hash function.
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
What that means to us is that it is impossible to find two different
objects with the same name. This has a number of advantages; among
others:
- Git can quickly determine whether two objects are identical or not,
just by comparing names.
Fix some typos, punctuation, missing words, minor markup. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:00:03 +02:00
- Since object names are computed the same way in every repository, the
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
same content stored in two repositories will always be stored under
the same name.
- Git can detect errors when it reads an object, by checking that the
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
object's name is still the SHA-1 hash of its contents.
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
(See <<object-details>> for the details of the object formatting and
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
SHA-1 calculation.)
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
There are four different types of objects: "blob", "tree", "commit", and
"tag".
- A <<def_blob_object,"blob" object>> is used to store file data.
user-manual: typo and grammar fixes Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-08 22:00:30 +02:00
- A <<def_tree_object,"tree" object>> ties one or more
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
"blob" objects into a directory structure. In addition, a tree object
can refer to other tree objects, thus creating a directory hierarchy.
- A <<def_commit_object,"commit" object>> ties such directory hierarchies
manual: Fix or remove em dashes. em dashes were used inconsistently in the manual. This changes them to the way they are used in US English. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:05:30 +02:00
together into a <<def_DAG,directed acyclic graph>> of revisions--each
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
commit contains the object name of exactly one tree designating the
directory hierarchy at the time of the commit. In addition, a commit
refers to "parent" commit objects that describe the history of how we
arrived at that directory hierarchy.
- A <<def_tag_object,"tag" object>> symbolically identifies and can be
used to sign other objects. It contains the object name and type of
another object, a symbolic name (of course!) and, optionally, a
signature.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
The object types in some more detail:
user-manual: reorder commit, blob, tree discussion 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>
2007-09-01 05:26:38 +02:00
[[commit-object]]
Commit Object
~~~~~~~~~~~~~
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
The "commit" object links a physical state of a tree with a description
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
of how we got there and why. Use the `--pretty=raw` option to
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
commit:
------------------------------------------------
$ git show -s --pretty=raw 2be7fcb476
commit 2be7fcb4764f2dbcee52635b91fedb1b3dcf7ab4
tree fb3a8bdd0ceddd019615af4d57a53f43d8cee2bf
parent 257a84d9d02e90447b149af58b271c19405edb6a
author Dave Watson <dwatson@mimvista.com> 1187576872 -0400
committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700
Fix misspelling of 'suppress' in docs
Signed-off-by: Junio C Hamano <gitster@pobox.com>
------------------------------------------------
As you can see, a commit is defined by:
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
- a tree: The SHA-1 name of a tree object (as defined below), representing
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
the contents of a directory at a certain point in time.
doc: A few minor copy edits. - (glossary) the quotes around the Wikipedia URL prevented its linkification in frontends that support it; remove them - (manual) newer version (SHA-1) == following, older == preceding, not the other way around - trivial typo and wording fixes Signed-off-by: Štěpán Němec <stepnem@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-07-15 00:20:36 +02:00
- parent(s): The SHA-1 name(s) of some number of commits which represent the
Fix spelling mistakes in user manual Signed-off-by: Shawn Bohrer <shawn.bohrer@gmail.com> Acked-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-13 05:36:21 +01:00
immediately previous step(s) in the history of the project. The
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
example above has one parent; merge commits may have more than
one. A commit with no parents is called a "root" commit, and
represents the initial revision of a project. Each project must have
at least one root. A project can also have multiple roots, though
that isn't common (or necessarily a good idea).
- an author: The name of the person responsible for this change, together
with its date.
- a committer: The name of the person who actually created the commit,
with the date it was done. This may be different from the author, for
example, if the author was someone who wrote a patch and emailed it
to the person who used it to create the commit.
- a comment describing this commit.
Note that a commit does not itself contain any information about what
actually changed; all changes are calculated by comparing the contents
of the tree referred to by this commit with the trees associated with
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
its parents. In particular, Git does not attempt to record file renames
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
explicitly, though it can identify cases where the existence of the same
file data at changing paths suggests a rename. (See, for example, the
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`-M` option to linkgit:git-diff[1]).
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
A commit is usually created by linkgit:git-commit[1], which creates a
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
commit whose parent is normally the current HEAD, and whose tree is
taken from the content currently stored in the index.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[tree-object]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Tree Object
user-manual: adjust section levels in "git internals" 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>
2007-08-31 04:49:33 +02:00
~~~~~~~~~~~
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The ever-versatile linkgit:git-show[1] command can also be used to
examine tree objects, but linkgit:git-ls-tree[1] will give you more
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
details:
------------------------------------------------
$ git ls-tree fb3a8bdd0ce
100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c .gitignore
100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d .mailmap
100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING
040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745 Documentation
100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200 GIT-VERSION-GEN
100644 blob 289b046a443c0647624607d471289b2c7dcd470b INSTALL
100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1 Makefile
100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52 README
...
------------------------------------------------
As you can see, a tree object contains a list of entries, each with a
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
mode, object type, SHA-1 name, and name, sorted by name. It represents
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
the contents of a single directory tree.
The object type may be a blob, representing the contents of a file, or
another tree, representing the contents of a subdirectory. Since trees
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
and blobs, like all other objects, are named by the SHA-1 hash of their
contents, two trees have the same SHA-1 name if and only if their
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
contents (including, recursively, the contents of all subdirectories)
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
are identical. This allows Git to quickly determine the differences
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
between two related tree objects, since it can ignore any entries with
identical object names.
(Note: in the presence of submodules, trees may also have commits as
user-manual: Explain what submodules are good for. Rework the introduction to the Submodules section to explain why someone would use them, and fix up submodule references from the tree-object and todo sections. Signed-off-by: Michael Smith <msmith@cbnco.com> Acked-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-09-25 14:44:38 +02:00
entries. See <<submodules>> for documentation.)
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Note that the files all have mode 644 or 755: Git actually only pays
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
attention to the executable bit.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: reorder commit, blob, tree discussion 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>
2007-09-01 05:26:38 +02:00
[[blob-object]]
Blob Object
~~~~~~~~~~~
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
You can use linkgit:git-show[1] to examine the contents of a blob; take,
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
for example, the blob in the entry for `COPYING` from the tree above:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
------------------------------------------------
$ git show 6ff87c4664
Note that the only valid version of the GPL as far as this project
is concerned is _this_ particular version of the license (ie v2, not
v2.2 or v3.x or whatever), unless explicitly otherwise stated.
...
------------------------------------------------
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
A "blob" object is nothing but a binary blob of data. It doesn't refer
to anything else or have attributes of any kind.
Since the blob is entirely defined by its data, if two files in a
directory tree (or in multiple different versions of the repository)
have the same contents, they will share the same blob object. The object
is totally independent of its location in the directory tree, and
renaming a file does not change the object that file is associated with.
Note that any tree or blob object can be examined using
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-show[1] with the <revision>:<path> syntax. This can
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
sometimes be useful for browsing the contents of a tree that is not
currently checked out.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[trust]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Trust
user-manual: adjust section levels in "git internals" 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>
2007-08-31 04:49:33 +02:00
~~~~~
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
If you receive the SHA-1 name of a blob from one source, and its contents
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
from another (possibly untrusted) source, you can still trust that those
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
contents are correct as long as the SHA-1 name agrees. This is because
the SHA-1 is designed so that it is infeasible to find different contents
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
that produce the same hash.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
Similarly, you need only trust the SHA-1 name of a top-level tree object
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
to trust the contents of the entire directory that it refers to, and if
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
you receive the SHA-1 name of a commit from a trusted source, then you
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
can easily verify the entire history of commits reachable through
parents of that commit, and all of those contents of the trees referred
to by those commits.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
So to introduce some real trust in the system, the only thing you need
to do is to digitally sign just 'one' special note, which includes the
name of a top-level commit. Your digital signature shows others
that you trust that commit, and the immutability of the history of
commits tells others that they can trust the whole history.
In other words, you can easily validate a whole archive by just
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
sending out a single email that tells the people the name (SHA-1 hash)
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
of the top commit, and digitally sign that email using something
like GPG/PGP.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
To assist in this, Git also provides the tag object...
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[tag-object]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Tag Object
user-manual: adjust section levels in "git internals" 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>
2007-08-31 04:49:33 +02:00
~~~~~~~~~~
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
A tag object contains an object, object type, tag name, the name of the
person ("tagger") who created the tag, and a message, which may contain
user-manual: typo and grammar fixes Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-08 22:00:30 +02:00
a signature, as can be seen using linkgit:git-cat-file[1]:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
------------------------------------------------
$ git cat-file tag v1.5.0
object 437b1b20df4b356c9342dac8d38849f24ef44f27
type commit
tag v1.5.0
tagger Junio C Hamano <junkio@cox.net> 1171411200 +0000
GIT 1.5.0
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
iD8DBQBF0lGqwMbZpPMRm5oRAuRiAJ9ohBLd7s2kqjkKlq1qqC57SbnmzQCdG4ui
nLE/L9aUXdWeTFPron96DLA=
=2E+0
-----END PGP SIGNATURE-----
------------------------------------------------
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
See the linkgit:git-tag[1] command to learn how to create and verify tag
objects. (Note that linkgit:git-tag[1] can also be used to create
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
"lightweight tags", which are not tag objects at all, but just simple
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
references whose names begin with `refs/tags/`).
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
[[pack-files]]
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
How Git stores objects efficiently: pack files
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
user-manual: fix introduction to packfiles Actually I don't think we've previously mentioned .git/objects, so we need a different introduction here. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:27:18 +02:00
Newly created objects are initially created in a file named after the
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
object's SHA-1 hash (stored in `.git/objects`).
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
Unfortunately this system becomes inefficient once a project has a
lot of objects. Try this on an old project:
------------------------------------------------
$ git count-objects
6930 objects, 47620 kilobytes
------------------------------------------------
The first number is the number of objects which are kept in
individual files. The second is the amount of space taken up by
those "loose" objects.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
You can save space and make Git faster by moving these loose objects in
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
to a "pack file", which stores a group of objects in an efficient
compressed format; the details of how pack files are formatted can be
Documentation: make AsciiDoc links always point to HTML files AsciiDoc's "link" is supposed to create hyperlinks for HTML output, so prefer a "link" to point to an HTML file instead of a text file if an HTML version of the file is being generated. For RelNotes, keep pointing to text files as no equivalent HTML files are generated. If appropriate, also update the link description to not contain the linked file's extension. Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-06 22:03:22 +02:00
found in link:technical/pack-format.html[pack format].
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
To put the loose objects into a pack, just run git repack:
------------------------------------------------
$ git repack
Use current output for "git repack" Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:56:50 +02:00
Counting objects: 6020, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (6020/6020), done.
Writing objects: 100% (6020/6020), done.
Total 6020 (delta 4070), reused 0 (delta 0)
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
------------------------------------------------
Use current output for "git repack" Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:56:50 +02:00
This creates a single "pack file" in .git/objects/pack/
containing all currently unpacked objects. You can then run
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
------------------------------------------------
$ git prune
------------------------------------------------
to remove any of the "loose" objects that are now contained in the
pack. This will also remove any unreferenced objects (which may be
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
created when, for example, you use `git reset` to remove a commit).
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
You can verify that the loose objects are gone by looking at the
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`.git/objects` directory or by running
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
------------------------------------------------
$ git count-objects
0 objects, 0 kilobytes
------------------------------------------------
Although the object files are gone, any commands that refer to those
objects will work exactly as they did before.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-gc[1] command performs packing, pruning, and more for
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
you, so is normally the only high-level command you need.
[[dangling-objects]]
Dangling objects
~~~~~~~~~~~~~~~~
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-fsck[1] command will sometimes complain about dangling
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
objects. They are not a problem.
The most common cause of dangling objects is that you've rebased a
branch, or you have pulled from somebody else who rebased a branch--see
<<cleaning-up-history>>. In that case, the old head of the original
branch still exists, as does everything it pointed to. The branch
pointer itself just doesn't, since you replaced it with another one.
There are also other situations that cause dangling objects. For
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
example, a "dangling blob" may arise because you did a `git add` of a
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
file, but then, before you actually committed it and made it part of the
bigger picture, you changed something else in that file and committed
manual: Fix or remove em dashes. em dashes were used inconsistently in the manual. This changes them to the way they are used in US English. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:05:30 +02:00
that *updated* thing--the old state that you added originally ends up
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
not being pointed to by any commit or tree, so it's now a dangling blob
object.
Similarly, when the "recursive" merge strategy runs, and finds that
there are criss-cross merges and thus more than one merge base (which is
fairly unusual, but it does happen), it will generate one temporary
midway tree (or possibly even more, if you had lots of criss-crossing
merges and more than two merge bases) as a temporary internal merge
base, and again, those are real objects, but the end result will not end
up pointing to them, so they end up "dangling" in your repository.
Generally, dangling objects aren't anything to worry about. They can
even be very useful: if you screw something up, the dangling objects can
be how you recover your old tree (say, you did a rebase, and realized
manual: Fix or remove em dashes. em dashes were used inconsistently in the manual. This changes them to the way they are used in US English. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:05:30 +02:00
that you really didn't want to--you can look at what dangling objects
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
you have, and decide to reset your head to some old dangling state).
For commits, you can just use:
------------------------------------------------
$ gitk <dangling-commit-sha-goes-here> --not --all
------------------------------------------------
This asks for all the history reachable from the given commit but not
from any branch, tag, or other reference. If you decide it's something
you want, you can always create a new reference to it, e.g.,
------------------------------------------------
$ git branch recovered-branch <dangling-commit-sha-goes-here>
------------------------------------------------
For blobs and trees, you can't do the same, but you can still examine
them. You can just do
------------------------------------------------
$ git show <dangling-blob/tree-sha-goes-here>
------------------------------------------------
to show what the contents of the blob were (or, for a tree, basically
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
what the `ls` for that directory was), and that may give you some idea
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
of what the operation was that left that dangling object.
Usually, dangling blobs and trees aren't very interesting. They're
almost always the result of either being a half-way mergebase (the blob
will often even have the conflict markers from a merge in it, if you
have had conflicting merges that you fixed up by hand), or simply
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
because you interrupted a `git fetch` with ^C or something like that,
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
leaving _some_ of the new objects in the object database, but just
dangling and useless.
Anyway, once you are sure that you're not interested in any dangling
state, you can just prune all unreachable objects:
------------------------------------------------
$ git prune
------------------------------------------------
"git prune" is safe "git prune" is safe in case of concurrent accesses to a repository but using it in such a case is not recommended. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:05:50 +02:00
and they'll be gone. (You should only run `git prune` on a quiescent
manual: Fix or remove em dashes. em dashes were used inconsistently in the manual. This changes them to the way they are used in US English. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:05:30 +02:00
repository--it's kind of like doing a filesystem fsck recovery: you
user-manual: move packfile and dangling object discussion The discussions of packfiles and dangling objects both belong in the object database section. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-09 04:13:53 +02:00
don't want to do that while the filesystem is mounted.
"git prune" is safe "git prune" is safe in case of concurrent accesses to a repository but using it in such a case is not recommended. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:05:50 +02:00
`git prune` is designed not to cause any harm in such cases of concurrent
accesses to a repository but you might receive confusing or scary messages.)
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
[[recovering-from-repository-corruption]]
Recovering from repository corruption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
By design, Git treats data trusted to it with caution. However, even in
the absence of bugs in Git itself, it is still possible that hardware or
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
operating system errors could corrupt data.
The first defense against such problems is backups. You can back up a
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Git directory using clone, or just using cp, tar, or any other backup
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
mechanism.
As a last resort, you can search for the corrupted objects and attempt
to replace them by hand. Back up your repository before attempting this
in case you corrupt things even more in the process.
We'll assume that the problem is a single missing or corrupted blob,
Fix spelling mistakes in user manual Signed-off-by: Shawn Bohrer <shawn.bohrer@gmail.com> Acked-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-13 05:36:21 +01:00
which is sometimes a solvable problem. (Recovering missing trees and
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
especially commits is *much* harder).
Before starting, verify that there is corruption, and figure out where
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
it is with linkgit:git-fsck[1]; this may be time-consuming.
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
Assume the output looks like this:
------------------------------------------------
fsck: --no-dangling omits "dangling object" information The default output from "fsck" is often overwhelmed by informational message on dangling objects, especially if you do not repack often, and a real error can easily be buried. Add "--no-dangling" option to omit them, and update the user manual to demonstrate its use. Based on a patch by Clemens Buchacher, but reverted the part to change the default to --no-dangling, which is unsuitable for the first patch. The usual three-step procedure to break the backward compatibility over time needs to happen on top of this, if we were to go in that direction. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-02-28 23:55:39 +01:00
$ git fsck --full --no-dangling
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
to blob 4b9458b3786228369c63936db65827de3cc06200
missing blob 4b9458b3786228369c63936db65827de3cc06200
------------------------------------------------
Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6
points to it. If you could find just one copy of that missing blob
object, possibly in some other repository, you could move it into
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`.git/objects/4b/9458b3...` and be done. Suppose you can't. You can
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
still examine the tree that pointed to it with linkgit:git-ls-tree[1],
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
which might output something like:
------------------------------------------------
$ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore
100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap
100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING
...
100644 blob 4b9458b3786228369c63936db65827de3cc06200 myfile
...
------------------------------------------------
So now you know that the missing blob was the data for a file named
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`myfile`. And chances are you can also identify the directory--let's
say it's in `somedirectory`. If you're lucky the missing copy might be
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
the same as the copy you have checked out in your working tree at
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
`somedirectory/myfile`; you can test whether that's right with
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-hash-object[1]:
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
------------------------------------------------
$ git hash-object -w somedirectory/myfile
------------------------------------------------
which will create and store a blob object with the contents of
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
somedirectory/myfile, and output the SHA-1 of that object. if you're
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in
which case you've guessed right, and the corruption is fixed!
Otherwise, you need more information. How do you tell which version of
the file has been lost?
The easiest way to do this is with:
------------------------------------------------
$ git log --raw --all --full-history -- somedirectory/myfile
------------------------------------------------
Because you're asking for raw output, you'll now get something like
------------------------------------------------
commit abc
Author:
Date:
...
:100644 100644 4b9458b... newsha... M somedirectory/myfile
commit xyz
Author:
Date:
...
:100644 100644 oldsha... 4b9458b... M somedirectory/myfile
------------------------------------------------
doc: A few minor copy edits. - (glossary) the quotes around the Wikipedia URL prevented its linkification in frontends that support it; remove them - (manual) newer version (SHA-1) == following, older == preceding, not the other way around - trivial typo and wording fixes Signed-off-by: Štěpán Němec <stepnem@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-07-15 00:20:36 +02:00
This tells you that the immediately following version of the file was
"newsha", and that the immediately preceding version was "oldsha".
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
You also know the commit messages that went with the change from oldsha
to 4b9458b and with the change from 4b9458b to newsha.
If you've been committing small enough changes, you may now have a good
shot at reconstructing the contents of the in-between state 4b9458b.
If you can do that, you can now recreate the missing object with
------------------------------------------------
$ git hash-object -w <recreated-file>
------------------------------------------------
and your repository is good again!
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
(Btw, you could have ignored the `fsck`, and started with doing a
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
------------------------------------------------
$ git log --raw --all
------------------------------------------------
Merge branch 'maint' * maint: user-manual: recovering from corruption user-manual: clarify language about "modifying" old commits user-manual: failed push to public repository user-manual: define "branch" and "working tree" at start git-checkout: describe detached head correctly
2007-11-26 04:10:01 +01:00
and just looked for the sha of the missing object (4b9458b..) in that
user-manual: Fix 'you - Git' -> 'you--Git' typo Use an em-dash, not a hyphen, to join these clauses. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-10 16:10:39 +01:00
whole thing. It's up to you--Git does *have* a lot of information, it is
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
just missing one particular blob version.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[the-index]]
user-manual: rewrite index discussion 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>
2007-09-03 18:59:55 +02:00
The index
-----------
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
The index is a binary file (generally kept in `.git/index`) containing a
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
sorted list of path names, each with permissions and the SHA-1 of a blob
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
object; linkgit:git-ls-files[1] can show you the contents of the index:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: rewrite index discussion 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>
2007-09-03 18:59:55 +02:00
-------------------------------------------------
$ git ls-files --stage
100644 63c918c667fa005ff12ad89437f2fdc80926e21c 0 .gitignore
100644 5529b198e8d14decbe4ad99db3f7fb632de0439d 0 .mailmap
100644 6ff87c4664981e4397625791c8ea3bbb5f2279a3 0 COPYING
100644 a37b2152bd26be2c2289e1f57a292534a51a93c7 0 Documentation/.gitignore
100644 fbefe9a45b00a54b58d94d06eca48b03d40a50e0 0 Documentation/Makefile
...
100644 2511aef8d89ab52be5ec6a5e46236b4b6bcd07ea 0 xdiff/xtypes.h
100644 2ade97b2574a9f77e7ae4002a4e07a6a38e46d07 0 xdiff/xutils.c
100644 d5de8292e05e7c36c4b68857c1cf9855e3d2f70a 0 xdiff/xutils.h
-------------------------------------------------
Note that in older documentation you may see the index called the
"current directory cache" or just the "cache". It has three important
properties:
1. The index contains all the information necessary to generate a single
(uniquely determined) tree object.
+
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
For example, running linkgit:git-commit[1] generates this tree object
user-manual: rewrite index discussion 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>
2007-09-03 18:59:55 +02:00
from the index, stores it in the object database, and uses it as the
tree object associated with the new commit.
2. The index enables fast comparisons between the tree object it defines
and the working tree.
+
It does this by storing some additional data for each entry (such as
the last modified time). This data is not displayed above, and is not
stored in the created tree object, but it can be used to determine
quickly which files in the working directory differ from what was
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
stored in the index, and thus save Git from having to read all of the
user-manual: rewrite index discussion 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>
2007-09-03 18:59:55 +02:00
data from such files to look for changes.
3. It can efficiently represent information about merge conflicts
between different tree objects, allowing each pathname to be
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
associated with sufficient information about the trees involved that
user-manual: rewrite index discussion 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>
2007-09-03 18:59:55 +02:00
you can create a three-way merge between them.
+
We saw in <<conflict-resolution>> that during a merge the index can
store multiple versions of a single file (called "stages"). The third
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
column in the linkgit:git-ls-files[1] output above is the stage
user-manual: rewrite index discussion 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>
2007-09-03 18:59:55 +02:00
number, and will take on values other than 0 for files with merge
conflicts.
The index is thus a sort of temporary staging area, which is filled with
a tree which you are in the process of working on.
If you blow the index away entirely, you generally haven't lost any
information as long as you have the name of the tree that it described.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
[[submodules]]
Submodules
==========
user-manual: Explain what submodules are good for. Rework the introduction to the Submodules section to explain why someone would use them, and fix up submodule references from the tree-object and todo sections. Signed-off-by: Michael Smith <msmith@cbnco.com> Acked-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-09-25 14:44:38 +02:00
Large projects are often composed of smaller, self-contained modules. For
example, an embedded Linux distribution's source tree would include every
piece of software in the distribution with some local modifications; a movie
player might need to build against a specific, known-working version of a
decompression library; several independent programs might all share the same
build scripts.
With centralized revision control systems this is often accomplished by
including every module in one single repository. Developers can check out
all modules or only the modules they need to work with. They can even modify
files across several modules in a single commit while moving things around
or updating APIs and translations.
Git does not allow partial checkouts, so duplicating this approach in Git
would force developers to keep a local copy of modules they are not
interested in touching. Commits in an enormous checkout would be slower
than you'd expect as Git would have to scan every directory for changes.
If modules have a lot of local history, clones would take forever.
On the plus side, distributed revision control systems can much better
integrate with external sources. In a centralized model, a single arbitrary
snapshot of the external project is exported from its own revision control
and then imported into the local revision control on a vendor branch. All
the history is hidden. With distributed revision control you can clone the
entire external history and much more easily follow development and re-merge
local changes.
Git's submodule support allows a repository to contain, as a subdirectory, a
checkout of an external project. Submodules maintain their own identity;
the submodule support just stores the submodule repository location and
commit ID, so other developers who clone the containing project
("superproject") can easily clone all the submodules at the same revision.
Partial checkouts of the superproject are possible: you can tell Git to
clone none, some or all of the submodules.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-submodule[1] command is available since Git 1.5.3. Users
user-manual: Explain what submodules are good for. Rework the introduction to the Submodules section to explain why someone would use them, and fix up submodule references from the tree-object and todo sections. Signed-off-by: Michael Smith <msmith@cbnco.com> Acked-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-09-25 14:44:38 +02:00
with Git 1.5.2 can look up the submodule commits in the repository and
manually check them out; earlier versions won't recognize the submodules at
all.
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
Fix some typos and improve wording Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:59:21 +02:00
To see how submodule support works, create four example
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
repositories that can be used later as a submodule:
-------------------------------------------------
$ mkdir ~/git
$ cd ~/git
$ for i in a b c d
do
mkdir $i
cd $i
git init
echo "module $i" > $i.txt
git add $i.txt
git commit -m "Initial commit, submodule $i"
cd ..
done
-------------------------------------------------
Now create the superproject and add all the submodules:
-------------------------------------------------
$ mkdir super
$ cd super
$ git init
$ for i in a b c d
do
`git submodule add` now requires a <path> Signed-off-by: Abhijit Menon-Sen <ams@toroid.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-29 21:53:16 +02:00
git submodule add ~/git/$i $i
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
done
-------------------------------------------------
NOTE: Do not use local URLs here if you plan to publish your superproject!
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
See what files `git submodule` created:
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
-------------------------------------------------
$ ls -a
. .. .git .gitmodules a b c d
-------------------------------------------------
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
The `git submodule add <repo> <path>` command does a couple of things:
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
- It clones the submodule from `<repo>` to the given `<path>` under the
`git submodule add` now requires a <path> Signed-off-by: Abhijit Menon-Sen <ams@toroid.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-29 21:53:16 +02:00
current directory and by default checks out the master branch.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
- It adds the submodule's clone path to the linkgit:gitmodules[5] file and
user-manual: Explain what submodules are good for. Rework the introduction to the Submodules section to explain why someone would use them, and fix up submodule references from the tree-object and todo sections. Signed-off-by: Michael Smith <msmith@cbnco.com> Acked-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-09-25 14:44:38 +02:00
adds this file to the index, ready to be committed.
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
- It adds the submodule's current commit ID to the index, ready to be
committed.
Commit the superproject:
-------------------------------------------------
$ git commit -m "Add submodules a, b, c and d."
-------------------------------------------------
Now clone the superproject:
-------------------------------------------------
$ cd ..
$ git clone super cloned
$ cd cloned
-------------------------------------------------
The submodule directories are there, but they're empty:
-------------------------------------------------
$ ls -a a
. ..
$ git submodule status
-d266b9873ad50488163457f025db7cdd9683d88b a
-e81d457da15309b4fef4249aba9b50187999670d b
-c1536a972b9affea0f16e0680ba87332dc059146 c
-d96249ff5d57de5de093e6baff9e0aafa5276a74 d
-------------------------------------------------
NOTE: The commit object names shown above would be different for you, but they
should match the HEAD commit object names of your repositories. You can check
it by running `git ls-remote ../a`.
Pulling down the submodules is a two-step process. First run `git submodule
init` to add the submodule repository URLs to `.git/config`:
-------------------------------------------------
$ git submodule init
-------------------------------------------------
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Now use `git submodule update` to clone the repositories and check out the
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
commits specified in the superproject:
-------------------------------------------------
$ git submodule update
$ cd a
$ ls -a
. .. .git a.txt
-------------------------------------------------
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
One major difference between `git submodule update` and `git submodule add` is
that `git submodule update` checks out a specific commit, rather than the tip
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
of a branch. It's like checking out a tag: the head is detached, so you're not
working on a branch.
-------------------------------------------------
$ git branch
Use current "detached HEAD" message Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:56:04 +02:00
* (detached from d266b98)
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
master
-------------------------------------------------
If you want to make a change within a submodule and you have a detached head,
then you should create or checkout a branch, make your changes, publish the
change within the submodule, and then update the superproject to reference the
new commit:
-------------------------------------------------
$ git checkout master
-------------------------------------------------
or
-------------------------------------------------
$ git checkout -b fix-up
-------------------------------------------------
then
-------------------------------------------------
$ echo "adding a line again" >> a.txt
$ git commit -a -m "Updated the submodule from within the superproject."
$ git push
$ cd ..
$ git diff
diff --git a/a b/a
index d266b98..261dfac 160000
--- a/a
+++ b/a
@@ -1 +1 @@
-Subproject commit d266b9873ad50488163457f025db7cdd9683d88b
+Subproject commit 261dfac35cb99d380eb966e102c1197139f7fa24
$ git add a
$ git commit -m "Updated submodule a."
$ git push
-------------------------------------------------
You have to run `git submodule update` after `git pull` if you want to update
submodules, too.
Pitfalls with submodules
------------------------
Always publish the submodule change before publishing the change to the
superproject that references it. If you forget to publish the submodule change,
others won't be able to clone the repository:
-------------------------------------------------
$ cd ~/git/super/a
$ echo i added another line to this file >> a.txt
$ git commit -a -m "doing it wrong this time"
$ cd ..
$ git add a
$ git commit -m "Updated submodule a again."
$ git push
$ cd ~/git/cloned
$ git pull
$ git submodule update
error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git.
Did you forget to 'git add'?
Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
-------------------------------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
In older Git versions it could be easily forgotten to commit new or modified
Updates for dirty submodules in release notes and user manual In the release notes "git status" was not mentioned, also shortly explain the "-dirty" output generated by diff. Added a paragraph to the "Pitfalls with submodules" section in user-manual.txt describing new and old behavior of "git status" and "git diff" for dirty submodules. Signed-off-by: Jens Lehmann <Jens.Lehmann@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-01 19:09:39 +01:00
files in a submodule, which silently leads to similar problems as not pushing
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff`
Updates for dirty submodules in release notes and user manual In the release notes "git status" was not mentioned, also shortly explain the "-dirty" output generated by diff. Added a paragraph to the "Pitfalls with submodules" section in user-manual.txt describing new and old behavior of "git status" and "git diff" for dirty submodules. Signed-off-by: Jens Lehmann <Jens.Lehmann@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-01 19:09:39 +01:00
in the superproject show submodules as modified when they contain new or
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
modified files to protect against accidentally committing such a state. `git
diff` will also add a `-dirty` to the work tree side when generating patch
output or used with the `--submodule` option:
Updates for dirty submodules in release notes and user manual In the release notes "git status" was not mentioned, also shortly explain the "-dirty" output generated by diff. Added a paragraph to the "Pitfalls with submodules" section in user-manual.txt describing new and old behavior of "git status" and "git diff" for dirty submodules. Signed-off-by: Jens Lehmann <Jens.Lehmann@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-01 19:09:39 +01:00
-------------------------------------------------
$ git diff
diff --git a/sub b/sub
--- a/sub
+++ b/sub
@@ -1 +1 @@
-Subproject commit 3f356705649b5d566d97ff843cf193359229a453
+Subproject commit 3f356705649b5d566d97ff843cf193359229a453-dirty
$ git diff --submodule
Submodule sub 3f35670..3f35670-dirty:
-------------------------------------------------
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
You also should not rewind branches in a submodule beyond commits that were
ever recorded in any superproject.
It's not safe to run `git submodule update` if you've made and committed
changes within a submodule without checking out a branch first. They will be
silently overwritten:
-------------------------------------------------
$ cat a.txt
module a
$ echo line added from private2 >> a.txt
$ git commit -a -m "line added inside private2"
$ cd ..
$ git submodule update
Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b'
$ cd a
$ cat a.txt
module a
-------------------------------------------------
NOTE: The changes are still visible in the submodule's reflog.
user-manual: Flesh out uncommitted changes and submodule updates If you try and update a submodule with a dirty working directory, you get an error message like: $ git submodule update error: Your local changes to the following files would be overwritten by checkout: ... Please, commit your changes or stash them before you can switch branches. Aborting ... Mention this in the submodule notes. The previous phrase was short enough that I originally thought it might have been referring to the reflog note (obviously, uncommitted changes will not show up in the reflog either ;). Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-19 11:05:02 +01:00
If you have uncommitted changes in your submodule working tree, `git
submodule update` will not overwrite them. Instead, you get the usual
warning about not being able switch from a dirty branch.
User Manual: add a chapter for submodules Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-09-20 02:34:14 +02:00
user-manual: create new "low-level git operations" chapter 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>
2007-09-03 17:27:56 +02:00
[[low-level-operations]]
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Low-level Git operations
user-manual: create new "low-level git operations" chapter 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>
2007-09-03 17:27:56 +02:00
========================
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: create new "low-level git operations" chapter 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>
2007-09-03 17:27:56 +02:00
Many of the higher-level commands were originally implemented as shell
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
scripts using a smaller core of low-level Git commands. These can still
be useful when doing unusual things with Git, or just as a way to
user-manual: create new "low-level git operations" chapter 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>
2007-09-03 17:27:56 +02:00
understand its inner workings.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
[[object-manipulation]]
Object access and manipulation
------------------------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-cat-file[1] command can show the contents of any object,
though the higher-level linkgit:git-show[1] is usually more useful.
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-commit-tree[1] command allows constructing commits with
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
arbitrary parents and trees.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
A tree can be created with linkgit:git-write-tree[1] and its data can be
accessed by linkgit:git-ls-tree[1]. Two trees can be compared with
linkgit:git-diff-tree[1].
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
A tag is created with linkgit:git-mktag[1], and the signature can be
verified by linkgit:git-verify-tag[1], though it is normally simpler to
use linkgit:git-tag[1] for both.
user-manual: rewrite object database discussion 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>
2007-06-10 21:15:08 +02:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[the-workflow]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
The Workflow
------------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
High-level operations such as linkgit:git-commit[1],
linkgit:git-checkout[1] and linkgit:git-reset[1] work by moving data
Fix some typos, punctuation, missing words, minor markup. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:00:03 +02:00
between the working tree, the index, and the object database. Git
provides low-level operations which perform each of these steps
individually.
user-manual: create new "low-level git operations" chapter 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>
2007-09-03 17:27:56 +02:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Generally, all Git operations work on the index file. Some operations
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
work *purely* on the index file (showing the current state of the
user-manual: create new "low-level git operations" chapter 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>
2007-09-03 17:27:56 +02:00
index), but most operations move data between the index file and either
the database or the working directory. Thus there are four main
combinations:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[working-directory-to-index]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
working directory -> index
~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The linkgit:git-update-index[1] command updates the index with
user-manual: create new "low-level git operations" chapter 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>
2007-09-03 17:27:56 +02:00
information from the working directory. You generally update the
index information by just specifying the filename you want to update,
like so:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: create new "low-level git operations" chapter 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>
2007-09-03 17:27:56 +02:00
$ git update-index filename
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
but to avoid common mistakes with filename globbing etc, the command
will not normally add totally new entries or remove old entries,
i.e. it will normally just update existing cache entries.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
To tell Git that yes, you really do realize that certain files no
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
longer exist, or that new files should be added, you
should use the `--remove` and `--add` flags respectively.
NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
necessarily be removed: if the files still exist in your directory
structure, the index will be updated with their new status, not
Replace the word 'update-cache' by 'update-index' everywhere Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-30 12:35:23 +01:00
removed. The only thing `--remove` means is that update-index will be
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
considering a removed file to be a valid thing, and if the file really
does not exist any more, it will update the index accordingly.
Documentation: more "git-" versus "git " changes With git-commands moving out of $(bindir), it is useful to make a clearer distinction between the git subcommand 'git-whatever' and the command you type, `git whatever <options>`. So we use a dash after "git" when referring to the former and not the latter. I already sent a patch doing this same thing, but I missed some spots. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-03 07:28:15 +02:00
As a special case, you can also do `git update-index --refresh`, which
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
will refresh the "stat" information of each index to match the current
stat information. It will 'not' update the object status itself, and
it will only update the fields that are used to quickly test whether
an object still matches its old backing store object.
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
The previously introduced linkgit:git-add[1] is just a wrapper for
linkgit:git-update-index[1].
user-manual: create new "low-level git operations" chapter 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>
2007-09-03 17:27:56 +02:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[index-to-object-database]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
index -> object database
~~~~~~~~~~~~~~~~~~~~~~~~
You write your current index file to a "tree" object with the program
-------------------------------------------------
user-manual: create new "low-level git operations" chapter 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>
2007-09-03 17:27:56 +02:00
$ git write-tree
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
manual: Fix or remove em dashes. em dashes were used inconsistently in the manual. This changes them to the way they are used in US English. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:05:30 +02:00
that doesn't come with any options--it will just write out the
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
current index into the set of tree objects that describe that state,
and it will return the name of the resulting top-level tree. You can
use that tree to re-generate the index at any time by going in the
other direction:
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[object-database-to-index]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
object database -> index
~~~~~~~~~~~~~~~~~~~~~~~~
You read a "tree" file from the object database, and use that to
manual: Fix or remove em dashes. em dashes were used inconsistently in the manual. This changes them to the way they are used in US English. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:05:30 +02:00
populate (and overwrite--don't do this if your index contains any
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
unsaved state that you might want to restore later!) your current
index. Normal operation is just
-------------------------------------------------
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
$ git read-tree <SHA-1 of tree>
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
and your index file will now be equivalent to the tree that you saved
earlier. However, that is only your 'index' file: your working
directory contents have not been modified.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[index-to-working-directory]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
index -> working directory
~~~~~~~~~~~~~~~~~~~~~~~~~~
You update your working directory from the index by "checking out"
files. This is not a very common operation, since normally you'd just
keep your files updated, and rather than write to your working
directory, you'd tell the index files about the changes in your
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
working directory (i.e. `git update-index`).
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
However, if you decide to jump to a new version, or check out somebody
else's version, or just restore a previous tree, you'd populate your
index file with read-tree, and then you need to check out the result
with
-------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git checkout-index filename
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
or, if you want to check out all of the index, use `-a`.
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
NOTE! `git checkout-index` normally refuses to overwrite old files, so
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
if you have an old version of the tree already checked out, you will
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
need to use the `-f` flag ('before' the `-a` flag or the filename) to
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
'force' the checkout.
Finally, there are a few odds and ends which are not purely moving
from one representation to the other:
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[tying-it-all-together]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Tying it all together
~~~~~~~~~~~~~~~~~~~~~
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
To commit a tree you have instantiated with `git write-tree`, you'd
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
create a "commit" object that refers to that tree and the history
manual: Fix or remove em dashes. em dashes were used inconsistently in the manual. This changes them to the way they are used in US English. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:05:30 +02:00
behind it--most notably the "parent" commits that preceded it in
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
history.
Normally a "commit" has one parent: the previous state of the tree
before a certain change was made. However, sometimes it can have two
or more parent commits, in which case we call it a "merge", due to the
fact that such a commit brings together ("merges") two or more
previous states represented by other commits.
In other words, while a "tree" represents a particular directory state
Fix some typos and improve wording Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 19:59:21 +02:00
of a working directory, a "commit" represents that state in time,
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
and explains how we got there.
You create a commit object by giving it the tree that describes the
state at the time of the commit, and a list of parents:
-------------------------------------------------
Use parentheses and `...' where appropriate Remove some stray usage of other bracket types and asterisks for the same purpose. Signed-off-by: Štěpán Němec <stepnem@gmail.com> Acked-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-08 19:31:17 +02:00
$ git commit-tree <tree> -p <parent> [(-p <parent2>)...]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
and then giving the reason for the commit on stdin (either through
redirection from a pipe or file, or by just typing it at the tty).
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
`git commit-tree` will return the name of the object that represents
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
that commit, and you should save it away for later use. Normally,
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
you'd commit a new `HEAD` state, and while Git doesn't care where you
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
save the note about that state, in practice we tend to just write the
result to the file pointed at by `.git/HEAD`, so that we can always see
what the last committed state was.
Remove irrelevant reference from "Tying it all together" Sorry Jon, but this might not be of any help to new Git users ;) Acked-by: Jon Loeliger <jdl@jdl.com> Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:04:58 +02:00
Here is a picture that illustrates how various pieces fit together:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
------------
commit-tree
commit obj
+----+
| |
| |
V V
+-----------+
| Object DB |
| Backing |
| Store |
+-----------+
^
write-tree | |
tree obj | |
| | read-tree
| | tree obj
V
+-----------+
| Index |
| "cache" |
+-----------+
update-index ^
blob obj | |
| |
checkout-index -u | | checkout-index
stat | | blob obj
V
+-----------+
| Working |
| Directory |
+-----------+
------------
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[examining-the-data]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Examining the data
------------------
You can examine the data represented in the object database and the
index with various helper tools. For every object, you can use
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
linkgit:git-cat-file[1] to examine details about the
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
object:
-------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git cat-file -t <objectname>
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
shows the type of the object, and once you have the type (which is
usually implicit in where you find the object), you can use
-------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git cat-file blob|tree|commit|tag <objectname>
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
to show its contents. NOTE! Trees have binary content, and as a result
there is a special helper for showing that content, called
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
`git ls-tree`, which turns the binary content into a more easily
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
readable form.
It's especially instructive to look at "commit" objects, since those
tend to be small and fairly self-explanatory. In particular, if you
follow the convention of having the top commit name in `.git/HEAD`,
you can do
-------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git cat-file commit HEAD
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
to see what the top commit was.
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[merging-multiple-trees]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Merging multiple trees
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
----------------------
Improve section "Merging multiple trees" Remove unnecessary quoting. Simplify description of three-way merge. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:03:09 +02:00
Git can help you perform a three-way merge, which can in turn be
used for a many-way merge by repeating the merge procedure several
times. The usual situation is that you only do one three-way merge
(reconciling two lines of history) and commit the result, but if
you like to, you can merge several branches in one go.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Improve section "Merging multiple trees" Remove unnecessary quoting. Simplify description of three-way merge. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:03:09 +02:00
To perform a three-way merge, you start with the two commits you
want to merge, find their closest common parent (a third commit),
and compare the trees corresponding to these three commits.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Improve section "Merging multiple trees" Remove unnecessary quoting. Simplify description of three-way merge. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:03:09 +02:00
To get the "base" for the merge, look up the common parent of two
commits:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git merge-base <commit1> <commit2>
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
Improve section "Merging multiple trees" Remove unnecessary quoting. Simplify description of three-way merge. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27 20:03:09 +02:00
This prints the name of a commit they are both based on. You should
now look up the tree objects of those commits, which you can easily
do with
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git cat-file commit <commitname> | head -1
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
since the tree object information is always the first line in a commit
object.
user-manual: rewrap a few long lines Rewrap some long lines. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-29 07:33:55 +01:00
Once you know the three trees you are going to merge (the one "original"
user-manual: miscellaneous editing 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>
2007-05-07 06:56:45 +02:00
tree, aka the common tree, and the two "result" trees, aka the branches
user-manual: rewrap a few long lines Rewrap some long lines. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-29 07:33:55 +01:00
you want to merge), you do a "merge" read into the index. This will
complain if it has to throw away your old index contents, so you should
manual: Fix or remove em dashes. em dashes were used inconsistently in the manual. This changes them to the way they are used in US English. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:05:30 +02:00
make sure that you've committed those--in fact you would normally
user-manual: rewrap a few long lines Rewrap some long lines. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-29 07:33:55 +01:00
always do a merge against your last commit (which should thus match what
you have in your current index anyway).
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
To do the merge, do
-------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git read-tree -m -u <origtree> <yourtree> <targettree>
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
which will do all trivial merge operations for you directly in the
index file, and you can just write the result out with
Documentation: more "git-" versus "git " changes With git-commands moving out of $(bindir), it is useful to make a clearer distinction between the git subcommand 'git-whatever' and the command you type, `git whatever <options>`. So we use a dash after "git" when referring to the former and not the latter. I already sent a patch doing this same thing, but I missed some spots. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-03 07:28:15 +02:00
`git write-tree`.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[merging-multiple-trees-2]]
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Merging multiple trees, continued
---------------------------------
Sadly, many merges aren't trivial. If there are files that have
Fix some typos, punctuation, missing words, minor markup. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:00:03 +02:00
been added, moved or removed, or if both branches have modified the
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
same file, you will be left with an index tree that contains "merge
entries" in it. Such an index tree can 'NOT' be written out to a tree
object, and you will have to resolve any such merge clashes using
other tools before you can write out the result.
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
You can examine such index state with `git ls-files --unmerged`
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
command. An example:
------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git read-tree -m $orig HEAD $target
$ git ls-files --unmerged
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c
100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c
100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c
------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
Each line of the `git ls-files --unmerged` output begins with
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
the blob mode bits, blob SHA-1, 'stage number', and the
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
filename. The 'stage number' is Git's way to say which tree it
doc: A few minor copy edits. - (glossary) the quotes around the Wikipedia URL prevented its linkification in frontends that support it; remove them - (manual) newer version (SHA-1) == following, older == preceding, not the other way around - trivial typo and wording fixes Signed-off-by: Štěpán Němec <stepnem@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-07-15 00:20:36 +02:00
came from: stage 1 corresponds to the `$orig` tree, stage 2 to
the `HEAD` tree, and stage 3 to the `$target` tree.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Earlier we said that trivial merges are done inside
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
`git read-tree -m`. For example, if the file did not change
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
from `$orig` to `HEAD` nor `$target`, or if the file changed
from `$orig` to `HEAD` and `$orig` to `$target` the same way,
obviously the final outcome is what is in `HEAD`. What the
above example shows is that file `hello.c` was changed from
`$orig` to `HEAD` and `$orig` to `$target` in a different way.
You could resolve this by running your favorite 3-way merge
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
program, e.g. `diff3`, `merge`, or Git's own merge-file, on
user-manual: miscellaneous editing 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>
2007-05-07 06:56:45 +02:00
the blob objects from these three stages yourself, like this:
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git cat-file blob 263414f... >hello.c~1
$ git cat-file blob 06fa6a2... >hello.c~2
$ git cat-file blob cc44c73... >hello.c~3
user-manual: miscellaneous editing 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>
2007-05-07 06:56:45 +02:00
$ git merge-file hello.c~2 hello.c~1 hello.c~3
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
------------------------------------------------
This would leave the merge result in `hello.c~2` file, along
with conflict markers if there are conflicts. After verifying
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
the merge result makes sense, you can tell Git what the final
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
merge result for this file is by:
-------------------------------------------------
$ mv -f hello.c~2 hello.c
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git update-index hello.c
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
When a path is in the "unmerged" state, running `git update-index` for
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
that path tells Git to mark the path resolved.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
The above is the description of a Git merge at the lowest level,
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
to help you understand what conceptually happens under the hood.
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
In practice, nobody, not even Git itself, runs `git cat-file` three times
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
for this. There is a `git merge-index` program that extracts the
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
stages to temporary files and calls a "merge" script on it:
-------------------------------------------------
Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-30 08:09:04 +02:00
$ git merge-index git-merge-one-file hello.c
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
-------------------------------------------------
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
and that is what higher level `git merge -s resolve` is implemented with.
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
user-manual: adjust section levels in "git internals" 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>
2007-08-31 04:49:33 +02:00
[[hacking-git]]
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Hacking Git
user-manual: adjust section levels in "git internals" 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>
2007-08-31 04:49:33 +02:00
===========
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
This chapter covers internal details of the Git implementation which
probably only Git developers need to understand.
user-manual: adjust section levels in "git internals" 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>
2007-08-31 04:49:33 +02:00
user-manual: move object format details to hacking-git chapter Most of this is probably only of interest to git developers. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-31 05:07:05 +02:00
[[object-details]]
Object storage format
---------------------
All objects have a statically determined "type" which identifies the
format of the object (i.e. how it is used, and how it can refer to other
objects). There are currently four different object types: "blob",
"tree", "commit", and "tag".
Regardless of object type, all objects share the following
characteristics: they are all deflated with zlib, and have a header
that not only specifies their type, but also provides size information
user-manual: the name of the hash function is SHA-1, not sha1 Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:27 +02:00
about the data in the object. It's worth noting that the SHA-1 hash
user-manual: move object format details to hacking-git chapter Most of this is probably only of interest to git developers. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-31 05:07:05 +02:00
that is used to name the object is the hash of the original data
plus this header, so `sha1sum` 'file' does not match the object name
for 'file'.
As a result, the general consistency of an object can always be tested
independently of the contents or the type of the object: all objects can
be validated by verifying that (a) their hashes match the content of the
file and (b) the object successfully inflates to a stream of bytes that
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
forms a sequence of
`<ascii type without space> + <space> + <ascii decimal size> +
<byte\0> + <binary object data>`.
user-manual: move object format details to hacking-git chapter Most of this is probably only of interest to git developers. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-31 05:07:05 +02:00
The structured objects can further have their structure and
connectivity to other objects verified. This is generally done with
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
the `git fsck` program, which generates a full dependency graph
user-manual: move object format details to hacking-git chapter Most of this is probably only of interest to git developers. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
2007-08-31 05:07:05 +02:00
of all objects, and verifies their internal consistency (in addition
to just verifying their superficial consistency through the hash).
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
[[birdview-on-the-source-code]]
user-manual: revise birdseye-view chapter 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>
2007-05-13 01:48:31 +02:00
A birds-eye view of Git's source code
-------------------------------------
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
user-manual: revise birdseye-view chapter 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>
2007-05-13 01:48:31 +02:00
It is not always easy for new developers to find their way through Git's
source code. This section gives you a little guidance to show where to
start.
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
user-manual: revise birdseye-view chapter 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>
2007-05-13 01:48:31 +02:00
A good place to start is with the contents of the initial commit, with:
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
----------------------------------------------------
user-manual: revise birdseye-view chapter 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>
2007-05-13 01:48:31 +02:00
$ git checkout e83c5163
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
----------------------------------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
The initial revision lays the foundation for almost everything Git has
user-manual: revise birdseye-view chapter 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>
2007-05-13 01:48:31 +02:00
today, but is small enough to read in one sitting.
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
user-manual: revise birdseye-view chapter 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>
2007-05-13 01:48:31 +02:00
Note that terminology has changed since that revision. For example, the
README in that revision uses the word "changeset" to describe what we
now call a <<def_commit_object,commit>>.
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
user-manual: typo and grammar fixes Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-08 22:00:30 +02:00
Also, we do not call it "cache" any more, but rather "index"; however, the
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
file is still called `cache.h`. Remark: Not much reason to change it now,
especially since there is no good single name for it anyway, because it is
basically _the_ header file which is included by _all_ of Git's C sources.
user-manual: revise birdseye-view chapter 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>
2007-05-13 01:48:31 +02:00
If you grasp the ideas in that initial commit, you should check out a
more recent version and skim `cache.h`, `object.h` and `commit.h`.
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
In the early days, Git (in the tradition of UNIX) was a bunch of programs
which were extremely simple, and which you used in scripts, piping the
output of one into another. This turned out to be good for initial
development, since it was easier to test new things. However, recently
many of these parts have become builtins, and some of the core has been
"libified", i.e. put into libgit.a for performance, portability reasons,
and to avoid code duplication.
By now, you know what the index is (and find the corresponding data
structures in `cache.h`), and that there are just a couple of object types
(blobs, trees, commits and tags) which inherit their common structure from
`struct object`, which is their first member (and thus, you can cast e.g.
`(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e.
get at the object name and flags).
Now is a good point to take a break to let this information sink in.
Next step: get familiar with the object naming. Read <<naming-commits>>.
There are quite a few ways to name an object (and not only revisions!).
All of these are handled in `sha1_name.c`. Just have a quick look at
the function `get_sha1()`. A lot of the special handling is done by
functions like `get_sha1_basic()` or the likes.
This is just to get you into the groove for the most libified part of Git:
the revision walker.
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Basically, the initial version of `git log` was a shell script:
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
----------------------------------------------------------------
$ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \
LESS=-S ${PAGER:-less}
----------------------------------------------------------------
What does this mean?
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
`git rev-list` is the original version of the revision walker, which
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
_always_ printed a list of revisions to stdout. It is still functional,
Change mentions of "git programs" to "git commands" Most of the docs and printouts refer to "commands" when discussing what the end users call via the "git" top-level program. We should refer them as "git programs" when we discuss the fact that the commands are implemented as separate programs, but in other contexts, it is better to use the term "git commands" consistently. Signed-off-by: Ori Avtalion <ori@avtalion.name> Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-08-07 16:24:21 +02:00
and needs to, since most new Git commands start out as scripts using
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
`git rev-list`.
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
`git rev-parse` is not as important any more; it was only used to filter out
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
options that were relevant for the different plumbing commands that were
called by the script.
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Most of what `git rev-list` did is contained in `revision.c` and
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
`revision.h`. It wraps the options in a struct named `rev_info`, which
controls how and what revisions are walked, and more.
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
The original job of `git rev-parse` is now taken by the function
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
`setup_revisions()`, which parses the revisions and the common command line
options for the revision walker. This information is stored in the struct
`rev_info` for later consumption. You can do your own command line option
parsing after calling `setup_revisions()`. After that, you have to call
`prepare_revision_walk()` for initialization, and then you can get the
commits one by one with the function `get_revision()`.
If you are interested in more details of the revision walking process,
just have a look at the first implementation of `cmd_log()`; call
docs: stop using asciidoc no-inline-literal In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: <tt><sub></tt> foo <tt></sub>bar</tt> which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor <author@example.com>` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26 10:51:57 +02:00
`git show v1.3.0~155^2~4` and scroll down to that function (note that you
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
no longer need to call `setup_pager()` directly).
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Nowadays, `git log` is a builtin, which means that it is _contained_ in the
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
command `git`. The source side of a builtin is
fix "builtin-*" references to be "builtin/*" Documentation and some comments still refer to files in builtin/ as 'builtin-*.[cho]'. Update these to show the correct location. Signed-off-by: Phil Hord <hordp@cisco.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Assisted-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-18 19:44:58 +02:00
- a function called `cmd_<bla>`, typically defined in `builtin/<bla.c>`
(note that older versions of Git used to have it in `builtin-<bla>.c`
instead), and declared in `builtin.h`.
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
- an entry in the `commands[]` array in `git.c`, and
- an entry in `BUILTIN_OBJECTS` in the `Makefile`.
Sometimes, more than one builtin is contained in one source file. For
fix "builtin-*" references to be "builtin/*" Documentation and some comments still refer to files in builtin/ as 'builtin-*.[cho]'. Update these to show the correct location. Signed-off-by: Phil Hord <hordp@cisco.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Assisted-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-18 19:44:58 +02:00
example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`,
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
since they share quite a bit of code. In that case, the commands which are
_not_ named like the `.c` file in which they live have to be listed in
`BUILT_INS` in the `Makefile`.
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
`git log` looks more complicated in C than it does in the original script,
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
but that allows for a much greater flexibility and performance.
Here again it is a good point to take a pause.
Lesson three is: study the code. Really, it is the best way to learn about
the organization of Git (after you know the basic concepts).
So, think about something which you are interested in, say, "how can I
access a blob just knowing the object name of it?". The first step is to
find a Git command with which you can do it. In this example, it is either
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
`git show` or `git cat-file`.
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
For the sake of clarity, let's stay with `git cat-file`, because it
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
- is plumbing, and
- was around even in the initial commit (it literally went only through
fix "builtin-*" references to be "builtin/*" Documentation and some comments still refer to files in builtin/ as 'builtin-*.[cho]'. Update these to show the correct location. Signed-off-by: Phil Hord <hordp@cisco.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Assisted-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-18 19:44:58 +02:00
some 20 revisions as `cat-file.c`, was renamed to `builtin/cat-file.c`
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
when made a builtin, and then saw less than 10 versions).
fix "builtin-*" references to be "builtin/*" Documentation and some comments still refer to files in builtin/ as 'builtin-*.[cho]'. Update these to show the correct location. Signed-off-by: Phil Hord <hordp@cisco.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Assisted-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-18 19:44:58 +02:00
So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
it does.
------------------------------------------------------------------
git_config(git_default_config);
if (argc != 3)
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
usage("git cat-file [-t|-s|-e|-p|<type>] <sha1>");
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
if (get_sha1(argv[2], sha1))
die("Not a valid object name %s", argv[2]);
------------------------------------------------------------------
Let's skip over the obvious details; the only really interesting part
here is the call to `get_sha1()`. It tries to interpret `argv[2]` as an
object name, and if it refers to an object which is present in the current
repository, it writes the resulting SHA-1 into the variable `sha1`.
Two things are interesting here:
- `get_sha1()` returns 0 on _success_. This might surprise some new
Git hackers, but there is a long tradition in UNIX to return different
manual: Fix or remove em dashes. em dashes were used inconsistently in the manual. This changes them to the way they are used in US English. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:05:30 +02:00
negative numbers in case of different errors--and 0 on success.
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
- the variable `sha1` in the function signature of `get_sha1()` is `unsigned
docs: stop using asciidoc no-inline-literal In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: <tt><sub></tt> foo <tt></sub>bar</tt> which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor <author@example.com>` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26 10:51:57 +02:00
char *`, but is actually expected to be a pointer to `unsigned
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
char[20]`. This variable will contain the 160-bit SHA-1 of the given
docs: stop using asciidoc no-inline-literal In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: <tt><sub></tt> foo <tt></sub>bar</tt> which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor <author@example.com>` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26 10:51:57 +02:00
commit. Note that whenever a SHA-1 is passed as `unsigned char *`, it
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
is the binary representation, as opposed to the ASCII representation in
user-manual: revise birdseye-view chapter 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>
2007-05-13 01:48:31 +02:00
hex characters, which is passed as `char *`.
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
You will see both of these things throughout the code.
Now, for the meat:
-----------------------------------------------------------------------------
case 0:
buf = read_object_with_reference(sha1, argv[1], &size, NULL);
-----------------------------------------------------------------------------
This is how you read a blob (actually, not only a blob, but any type of
object). To know how the function `read_object_with_reference()` actually
works, find the source code for it (something like `git grep
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
read_object_with | grep ":[a-z]"` in the Git repository), and read
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
the source.
To find out how the result can be used, just read on in `cmd_cat_file()`:
-----------------------------------
write_or_die(1, buf, size);
-----------------------------------
Sometimes, you do not know where to look for a feature. In many such cases,
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
it helps to search through the output of `git log`, and then `git show` the
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
corresponding commit.
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
Example: If you know that there was some test case for `git bundle`, but
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
do not remember where it was (yes, you _could_ `git grep bundle t/`, but that
does not illustrate the point!):
------------------------
$ git log --no-merges t/
------------------------
In the pager (`less`), just search for "bundle", go a few lines back,
and see that it is in commit 18449ab0... Now just copy this object name,
and paste it into the command line
-------------------
$ git show 18449ab0
-------------------
Voila.
Another example: Find out what to do in order to make some script a
builtin:
-------------------------------------------------
fix "builtin-*" references to be "builtin/*" Documentation and some comments still refer to files in builtin/ as 'builtin-*.[cho]'. Update these to show the correct location. Signed-off-by: Phil Hord <hordp@cisco.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Assisted-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-18 19:44:58 +02:00
$ git log --no-merges --diff-filter=A builtin/*.c
Add a birdview-on-the-source-code section to the user manual 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>
2007-05-10 12:36:15 +02:00
-------------------------------------------------
You see, Git is actually the best tool to find out about the source of Git
itself!
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[glossary]]
User Manual: Write "Git" instead of "GIT" In the Table of Contents, there is a notable inconsistency: first there is "GIT Glossary", followed by "Git Quick Reference" on the very next line. Running "grep -c" on user-manual.txt, I find 780 occurrrences of "git", 37 occurrences of "Git", and 9 occurrences of "GIT". In general, "git" is the preferred spelling, except at the beginning of a sentence. Therefore, change "GIT Glossary" to "Git Glossary" for consistency with the rest of the document. Looking at the other eight occurrences of "GIT" I found one other occurrence that should be changed: * The mention of "StGIT". Looking at the web pages for "Stacked Git" at http://www.procode.org/stgit, I only saw the spelling "StGit", except in http://wiki.procode.org/cgi-bin/wiki.cgi/StGIT_Tutorial, but that page was last updated in 2006. The other seven occurrences should not be changed: * Three occurrences were in the output of 'git show-branch' run on the git.git repository. * One occurrence was in the output of 'git cat-file'. * One occurrence was as part of the file name "GIT-VERSION-GEN". * Two occurrences were in comments in scripts quoted in a description of Tony Luck's workflow. Signed-off-by: Björn Gustavsson <bgustavsson@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-22 10:47:04 +01:00
Git Glossary
Documentation: convert "glossary" and "core-tutorial" to man pages This patch renames the following documents and at the same time converts them to the man format: core-tutorial.txt -> gitcore-tutorial.txt glossary.txt -> gitglossary.txt But as the glossary is included in the user manual and as the new gitglossary man page cannot be included as a whole in the user manual, the actual glossary content is now in its own "glossary-content.txt" new file. And this file is included by both the user manual and the gitglossary man page. Other documents that reference the above ones are changed accordingly and sometimes improved a little too. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-05-29 19:21:46 +02:00
============
include::glossary-content.txt[]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
[[git-quick-start]]
user-manual: quick-start updates 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>
2007-06-06 00:33:27 +02:00
Appendix A: Git Quick Reference
===============================
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
user-manual: quick-start updates 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>
2007-06-06 00:33:27 +02:00
This is a quick summary of the major commands; the previous chapters
explain how these work in more detail.
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
[[quick-creating-a-new-repository]]
Creating a new repository
-------------------------
From a tarball:
-----------------------------------------------
$ tar xzf project.tar.gz
$ cd project
$ git init
Initialized empty Git repository in .git/
$ git add .
$ git commit
-----------------------------------------------
From a remote repository:
-----------------------------------------------
$ git clone git://example.com/pub/project.git
$ cd project
-----------------------------------------------
[[managing-branches]]
Managing branches
-----------------
-----------------------------------------------
$ git branch # list all local branches in this repo
$ git checkout test # switch working directory to branch "test"
$ git branch new # create branch "new" starting at current HEAD
$ git branch -d new # delete branch "new"
-----------------------------------------------
Fix some typos, punctuation, missing words, minor markup. Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-10-09 23:00:03 +02:00
Instead of basing a new branch on current HEAD (the default), use:
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
-----------------------------------------------
$ git branch new test # branch named "test"
$ git branch new v2.6.15 # tag named v2.6.15
$ git branch new HEAD^ # commit before the most recent
$ git branch new HEAD^^ # commit before that
$ git branch new test~10 # ten commits before tip of branch "test"
-----------------------------------------------
Create and switch to a new branch at the same time:
-----------------------------------------------
$ git checkout -b new v2.6.15
-----------------------------------------------
Update and examine branches from the repository you cloned from:
-----------------------------------------------
$ git fetch # update
$ git branch -r # list
origin/master
origin/next
...
$ git checkout -b masterwork origin/master
-----------------------------------------------
Fetch a branch from a different repository, and give it a new
name in your repository:
-----------------------------------------------
$ git fetch git://example.com/project.git theirbranch:mybranch
$ git fetch git://example.com/project.git v2.6.15:mybranch
-----------------------------------------------
Keep a list of repositories you work with regularly:
-----------------------------------------------
$ git remote add example git://example.com/project.git
$ git remote # list remote repositories
example
origin
$ git remote show example # get details
* remote example
URL: git://example.com/project.git
Tracked remote branches
git-remote: list branches in vertical lists Previously, branches were listed on a single line in each section. But if there are many branches, then horizontal, line-wrapped lists are very inconvenient to scan for a human. This makes the lists vertical, i.e one branch per line is printed. Since "git remote" is porcelain, we can easily make this backwards-incompatible change. Signed-off-by: Johannes Sixt <j6t@kdbg.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-10-22 09:39:47 +02:00
master
next
...
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
$ git fetch example # update branches from example
$ git branch -r # list all remote branches
-----------------------------------------------
[[exploring-history]]
Exploring history
-----------------
-----------------------------------------------
$ gitk # visualize and browse history
$ git log # list all commits
$ git log src/ # ...modifying src/
$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15
$ git log master..test # ...in branch test, not in branch master
$ git log test..master # ...in branch master, but not in test
$ git log test...master # ...in one branch, not in both
$ git log -S'foo()' # ...where difference contain "foo()"
$ git log --since="2 weeks ago"
$ git log -p # show patches as well
$ git show # most recent commit
$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
$ git diff v2.6.15..HEAD # diff with current head
$ git grep "foo()" # search working directory for "foo()"
$ git grep v2.6.15 "foo()" # search old tree for "foo()"
$ git show v2.6.15:a.txt # look at old version of a.txt
-----------------------------------------------
Search for regressions:
-----------------------------------------------
$ git bisect start
$ git bisect bad # current version is bad
$ git bisect good v2.6.13-rc2 # last known good revision
Bisecting: 675 revisions left to test after this
# test here, then:
$ git bisect good # if this revision is good, or
$ git bisect bad # if this revision is bad.
# repeat until done.
-----------------------------------------------
[[making-changes]]
Making changes
--------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Make sure Git knows who to blame:
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
------------------------------------------------
$ cat >>~/.gitconfig <<\EOF
[user]
name = Your Name Comes Here
email = you@yourdomain.example.com
EOF
------------------------------------------------
Select file contents to include in the next commit, then make the
commit:
-----------------------------------------------
$ git add a.txt # updated file
$ git add b.txt # new file
$ git rm c.txt # old file
$ git commit
-----------------------------------------------
Or, prepare and create the commit in one step:
-----------------------------------------------
$ git commit d.txt # use latest content only of d.txt
$ git commit -a # use latest content of all tracked files
-----------------------------------------------
[[merging]]
Merging
-------
-----------------------------------------------
$ git merge test # merge branch "test" into the current branch
$ git pull git://example.com/project.git master
# fetch and merge in remote branch
$ git pull . test # equivalent to git merge test
-----------------------------------------------
[[sharing-your-changes]]
Sharing your changes
--------------------
Importing or exporting patches:
-----------------------------------------------
$ git format-patch origin..HEAD # format a patch for each commit
# in HEAD but not in origin
$ git am mbox # import patches from the mailbox "mbox"
-----------------------------------------------
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
Fetch a branch in a different Git repository, then merge into the
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
current branch:
-----------------------------------------------
$ git pull git://example.com/project.git theirbranch
-----------------------------------------------
Store the fetched branch into a local branch before merging into the
current branch:
-----------------------------------------------
$ git pull git://example.com/project.git theirbranch:mybranch
-----------------------------------------------
After creating commits on a local branch, update the remote
branch with your commits:
-----------------------------------------------
$ git push ssh://example.com/project.git mybranch:theirbranch
-----------------------------------------------
When remote and local branch are both named "test":
-----------------------------------------------
$ git push ssh://example.com/project.git test
-----------------------------------------------
Shortcut version for a frequently used remote repository:
-----------------------------------------------
$ git remote add example ssh://example.com/project.git
$ git push example test
-----------------------------------------------
[[repository-maintenance]]
Repository maintenance
----------------------
Check for corruption:
-----------------------------------------------
$ git fsck
-----------------------------------------------
Recompress, remove unused cruft:
-----------------------------------------------
$ git gc
-----------------------------------------------
user-manual: add section ID's 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>
2007-04-18 06:46:19 +02:00
[[todo]]
user-manual: move quick-start to an appendix 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>
2007-05-13 04:55:40 +02:00
Appendix B: Notes and todo list for this manual
===============================================
Documentation: expand preface and todo's 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>
2007-01-08 04:58:14 +01:00
This is a work in progress.
The basic requirements:
user-manual: todo updates and cleanup Format a couple lists. Reminder that we may want to add submodule documentation some day.
2007-09-03 05:28:49 +02:00
- It must be readable in order, from beginning to end, by someone
intelligent with a basic grasp of the UNIX command line, but without
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
any special knowledge of Git. If necessary, any other prerequisites
user-manual: todo updates and cleanup Format a couple lists. Reminder that we may want to add submodule documentation some day.
2007-09-03 05:28:49 +02:00
should be specifically mentioned as they arise.
- Whenever possible, section headings should clearly describe the task
they explain how to do, in language that requires no more knowledge
than necessary: for example, "importing patches into a project" rather
user-manual: remove some git-foo usage Also, use `git foo` when it make sense. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-04 11:38:23 +02:00
than "the `git am` command"
Documentation: expand preface and todo's 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>
2007-01-08 04:58:14 +01:00
Documentation: begin discussion of git-remote in user manual Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-09 06:18:09 +01:00
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.
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
Scan `Documentation/` for other stuff left out; in particular:
user-manual: todo updates and cleanup Format a couple lists. Reminder that we may want to add submodule documentation some day.
2007-09-03 05:28:49 +02:00
- howto's
user-manual: Standardize backtick quoting I tried to always use backticks for: * Paths and filenames (e.g. `.git/config`) * Compound refs (e.g. `origin/HEAD`) * Git commands (e.g. `git log`) * Command arguments (e.g. `--pretty`) * URLs (e.g. `git://`), as a subset of command arguments * Special characters (e.g. `+` in diffs). * Config options (e.g. `branch.<name>.remote`) Branch and tag names are sometimes set off with double quotes, sometimes set off with backticks, and sometimes left bare. I tried to judge when the intention was introducing new terms or conventions (double quotes), to reference a recently used command argument (backticks), or to reference the abstract branch/commit (left bare). Obviously these are not particularly crisp definitions, so my decisions are fairly arbitrary ;). When a reference had already been introduced, I changed further double-quoted instances to backticked instances. When new backticks increased the length of a line beyond others in that block, I re-wrapped blocks to 72 columns. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-25 23:53:00 +01:00
- some of `technical/`?
user-manual: todo updates and cleanup Format a couple lists. Reminder that we may want to add submodule documentation some day.
2007-09-03 05:28:49 +02:00
- hooks
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 07:20:38 +01:00
- list of commands in linkgit:git[1]
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Scan email archives for other stuff left out
Scan man pages to see if any assume more background than this manual
provides.
user-manual: rewrap, fix heading levels Fix some heading levels that prevented compile; rewrap some stuff. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-15 04:43:47 +01:00
Simplify beginning by suggesting disconnected head instead of
user-manual: reorganize fetch discussion, add internals, etc. 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>
2007-01-27 07:03:07 +01:00
temporary branch creation?
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
user-manual: rewrap, fix heading levels Fix some heading levels that prevented compile; rewrap some stuff. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-15 04:43:47 +01:00
Add more good examples. Entire sections of just cookbook examples
might be a good idea; maybe make an "advanced examples" section a
standard end-of-chapter section?
Documentation: add git user's manual 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>
2007-01-08 01:23:49 +01:00
Include cross-references to the glossary, where appropriate.
user-manual: minor "TODO" updates 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>
2007-01-29 07:43:33 +01:00
Document shallow clones? See draft 1.5.0 release notes for some
documentation.
Assorted typo fixes Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-04 05:49:16 +01:00
Add a section on working with other version control systems, including
user-manual: minor "TODO" updates 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>
2007-01-29 07:43:33 +01:00
CVS, Subversion, and just imports of series of release tarballs.
user-manual: point to README for gitweb information 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>
2007-01-30 18:43:36 +01:00
More details on gitweb?
user-manual: todo's Update todo's. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-30 18:48:48 +01:00
Write a chapter on using plumbing and writing scripts.
Documentation: user-manual todo Some more user-manual todo's: how to share objects between repositories, how to recover. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-02-06 08:55:07 +01:00
Alternates, clone -reference, etc.
user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-04 04:53:37 +01:00
More on recovery from repository corruption. See:
update URL to the marc.info mail archive The name marc.theaimsgroup.com is no longer active, and has migrated to marc.info. Signed-off-by: Ondřej Bílka <neleai@seznam.cz> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-07-22 10:02:17 +02:00
http://marc.info/?l=git&m=117263864820799&w=2
http://marc.info/?l=git&m=117147855503798&w=2
Reference in New Issue Copy Permalink