{"thread":{"id":"8402","subject":"[RFC PATCH] Add git quick reference","startedAt":"2007-06-02T18:24:23Z","lastAt":"2007-06-06T20:36:06Z","messageCount":4,"participants":["Jonas Fonseca","J. Bruce Fields","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"43819","messageId":"20070602182423.GC19952@diku.dk","threadId":"8402","inReplyTo":null,"subject":"[RFC PATCH] Add git quick reference","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2007-06-02T18:24:23Z","receivedAt":"2007-06-02T18:24:23Z","isPatch":true,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"It attempts to list some of the most commonly used commands, which should\ngive new users an idea of how to get started.\n\nAvailable both as a manpage (generated via a script) and HTML page.\n---\n Documentation/Makefile            |    8 ++-\n Documentation/asciidoc.conf       |    2 +\n Documentation/git-quick-ref.sh    |   67 ++++++++++++++++++++++\n Documentation/quick-reference.txt |  112 +++++++++++++++++++++++++++++++++++++\n 4 files changed, 187 insertions(+), 2 deletions(-)\n create mode 100755 Documentation/git-quick-ref.sh\n create mode 100644 Documentation/quick-reference.txt\n\n This is \"ported\" from the Cogito quick reference that I made (inspired\n by svn-ref) to serve as something to hand out for new users--a kinda\n cheat sheet. I don't know if git even needs another document in this\n category. However, contrary to some of the others, this document tries\n to be very brief, which might help impatient users. ;)\n\n Also, I am, myself, quite new to the git porcelain so any feedback on\n which commands should be included would be very much appreciated! I'd\n like to keep the format to 2 pages max, so there is still room for a\n few additions.\n\n See the end result at:\n http://jonas.nitro.dk/git/quick-reference.{html,pdf}\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3f92783..9dcabaf 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -3,7 +3,7 @@ MAN1_TXT= \\\n \t\t$(wildcard git-*.txt)) \\\n \tgitk.txt\n MAN5_TXT=gitattributes.txt\n-MAN7_TXT=git.txt\n+MAN7_TXT=git.txt git-quick-ref.txt\n \n DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n \n@@ -18,6 +18,7 @@ ARTICLES += hooks\n ARTICLES += everyday\n ARTICLES += git-tools\n ARTICLES += glossary\n+ARTICLES += quick-reference\n # with their own formatting rules.\n SP_ARTICLES = howto/revert-branch-rebase user-manual\n \n@@ -107,7 +108,7 @@ git.7 git.html: git.txt core-intro.txt\n \n clean:\n \trm -f *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 howto-index.txt howto/*.html doc.dep\n-\trm -f $(cmds_txt) *.made\n+\trm -f $(cmds_txt) *.made git-quick-ref.txt\n \n %.html : %.txt\n \trm -f $@+ $@\n@@ -129,6 +130,9 @@ clean:\n user-manual.xml: user-manual.txt user-manual.conf\n \t$(ASCIIDOC) -b docbook -d book $<\n \n+git-quick-ref.txt: quick-reference.txt\n+\t./git-quick-ref.sh $< > $@\n+\n XSLT = http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl\n XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n \ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex fa7dc94..546a074 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -12,6 +12,8 @@ caret=^\n startsb=&#91;\n endsb=&#93;\n tilde=&#126;\n+# Five non breaking spaces used for option indentation in the quick reference\n+qrefopt=&#160;&#160;&#160;&#160;&#160;\n \n ifdef::backend-docbook[]\n [gitlink-inlinemacro]\ndiff --git a/Documentation/git-quick-ref.sh b/Documentation/git-quick-ref.sh\nnew file mode 100755\nindex 0000000..65b02b3\n--- /dev/null\n+++ b/Documentation/git-quick-ref.sh\n@@ -0,0 +1,67 @@\n+#!/bin/sh\n+#\n+# Generate asciidoc manpage markup from Git quick reference file.\n+# Copyright (c) Jonas Fonseca, 2007\n+#\n+# Takes the path to the reference file. Prints the manpage to stdout.\n+\n+reffile=\"$1\"\n+\n+cat <<__END__\n+git-quick-ref(7)\n+================\n+\n+NAME\n+----\n+git-quick-ref - Git quick reference\n+\n+SYNOPSIS\n+--------\n+A list of frequently used commands grouped with related commands.\n+\n+DESCRIPTION\n+-----------\n+\n+__END__\n+\n+sed '\n+\t0,/^$/d\n+\t/^`---/d\n+\t/frame=\"none\"/,1d\n+\ts/\\\\$//\n+\ts/[*]\\([^*]*\\)[*]/\\1/g\n+\ts/[`]\\([^`]*\\)[`]/\\1/g\n+\ts/['\\'']\\([^'\\'']*\\)['\\'']/\\1/g\n+' < \"$reffile\" | \\\n+while read line; do\n+\tcol1=$(echo \"$line\" | cut -f 1)\n+\tcase \"$line\" in\n+\t*\":\")\n+\t\techo \"$line\"\n+\t\techo \"$line\" | sed \"s/[^~]/~/g\"\n+\t\techo\n+\t\techo \"[verse]\"\n+\t\tcontinue\n+\t\t;;\n+\t\"-----\"*|\"\")\n+\t\techo \"$line\" | sed 's/-/./g'\n+\t\tcontinue\n+\t\t;;\n+\t\"{qrefopt}\"*)\n+\t\tcol1=$(echo \"$col1\" | sed 's/.*qrefopt}/   /')\n+\t\t;;\n+\tesac\n+\tcol2=$(echo \"$line\" | sed 's/.*[\t]\\+//')\n+\tprintf \"%-30s  %s\\n\" \"$col1\" \"$col2\"\n+done\n+\n+cat << __END__\n+\n+DOCUMENTATION\n+-------------\n+Documentation by Jonas Fonseca and the git-list <git@vger.kernel.org>.\n+\n+GIT\n+---\n+Part of the gitlink:git[7] suite\n+__END__\ndiff --git a/Documentation/quick-reference.txt b/Documentation/quick-reference.txt\nnew file mode 100644\nindex 0000000..4ab8620\n--- /dev/null\n+++ b/Documentation/quick-reference.txt\n@@ -0,0 +1,112 @@\n+Git Quick Reference\n+===================\n+\n+[frame=\"none\"]\n+`-------------------------------`---------------------------------------------\n+Getting help:\n+------------------------------------------------------------------------------\n+*git help* 'command'\t\tor\n+*git* 'command' \\--help\t\tShow help for a command\n+------------------------------------------------------------------------------\n+\n+[frame=\"none\"]\n+`-------------------------------`---------------------------------------------\n+Repository creation:\n+------------------------------------------------------------------------------\n+*git init*\t\t\tCreate a repository in the current directory\n+*git clone* 'url'\t\tClone a remote repository into a subdirectory\n+------------------------------------------------------------------------------\n+\n+[frame=\"none\"]\n+`-------------------------------`---------------------------------------------\n+File operations:\n+------------------------------------------------------------------------------\n+*git add* 'path'\t\tAdd file or files in directory recursively\n+*git rm* 'path'\t\t\tRemove file or directory from the working tree\n+{qrefopt} -f\t\t\tForce deletion of file(s) from disk\n+*git mv* 'path' 'destination'\tMove file or directory to new location\n+{qrefopt} -f\t\t\tOverwrite existing destination files\n+*git checkout* '[rev]' 'file'\tRestore file from current branch or revision\n+{qrefopt} -f\t\t\tOverwrite uncommitted local changes\n+------------------------------------------------------------------------------\n+\n+[frame=\"none\"]\n+`-------------------------------`---------------------------------------------\n+Working tree:\n+------------------------------------------------------------------------------\n+*git status*\t\t\tShow status of the working tree\n+*git diff* '[path]'\t\tShow diff of changes in the working tree\n+*git diff* HEAD 'path'\t\tShow diff of stages and unstaged changes\n+*git add* 'path'\t\tStage file for commit\n+*git reset* HEAD 'path'\t\tUnstage file for commit\n+*git commit*\t\t\tCommit files that has been staged (with git-add)\n+{qrefopt} -a\t\t\tAutomatically stage all modified files\n+*git reset* \\--soft HEAD^\tUndo commit & keep changes in the working tree\n+*git reset* \\--hard HEAD^\tReset the working tree to the last commit\n+*git clean*\t\t\tClean unknown files from the working tree\n+------------------------------------------------------------------------------\n+\n+[frame=\"none\"]\n+`-------------------------------`---------------------------------------------\n+Examining History:\n+------------------------------------------------------------------------------\n+*git log* '[path]'\t\tView commit log, optionally for specific path\n+*git log* '[from[..to]]'\tView commit log for a given revision range\n+{qrefopt} \\--stat\t\tList diffstat for each revision\n+{qrefopt} -S'pattern'\t\tSearch history for changes matching pattern\n+*git blame* '[file]'\t\tShow file annotated with line modifications\n+------------------------------------------------------------------------------\n+\n+[frame=\"none\"]\n+`-------------------------------`---------------------------------------------\n+Remote repositories - 'remotes':\n+------------------------------------------------------------------------------\n+*git fetch* '[remote]'\t\tFetch changes from a remote repository\n+*git pull* '[remote]'\t\tFetch and merge changes from a remote repository\n+*git push* '[remote]'\t\tPush changes to a remote repository\n+*git remote*\t\t\tList remote repositories\n+*git remote add* 'remote' 'url'\tAdd remote to list of tracked repositories\n+------------------------------------------------------------------------------\n+\n+[frame=\"none\"]\n+`-------------------------------`---------------------------------------------\n+Branches:\n+------------------------------------------------------------------------------\n+*git checkout* 'branch'\t\tSwitch working tree to branch\n+{qrefopt} -b 'branch'\t\tCreate branch before switching to it\n+*git branch*\t\t\tList local branches\n+*git branch* -f\t'branch' 'rev'\tOverwrite existing branch, start from revision\n+*git merge* 'branch'\t\tMerge changes from branch\n+------------------------------------------------------------------------------\n+\n+[frame=\"none\"]\n+`-------------------------------`---------------------------------------------\n+Exporting and importing:\n+------------------------------------------------------------------------------\n+*git apply* - < 'file'\t\tApply patch from stdin\n+*git format-patch* 'from[..to]'\tFormat a patch with log message and diffstat\n+*git archive* 'rev' > 'file'\tExport snapshot of revision to file\n+{qrefopt} \\--prefix='dir'/\tNest all files in the snapshot in directory\n+{qrefopt} \\--format='[tar|zip]'\tSpecify archive format to use: 'tar' or 'zip'\n+------------------------------------------------------------------------------\n+\n+[frame=\"none\"]\n+`-------------------------------`---------------------------------------------\n+Tags:\n+------------------------------------------------------------------------------\n+*git tag* 'name' '[revision]'\tCreate tag for a given revision\n+{qrefopt} -s\t\t\tSign tag with your private key using GPG\n+{qrefopt} -l '[pattern]'\tList tags, optionally matching pattern\n+------------------------------------------------------------------------------\n+\n+[frame=\"none\"]\n+`-------------------------------`---------------------------------------------\n+File status flags:\n+------------------------------------------------------------------------------\n+`M` modified\t\t\tFile has been modified\n+`C` copy-edit\t\t\tFile has been copied and modified\n+`R` rename-edit\t\t\tFile has been renamed and modified\n+`A` added\t\t\tFile has been added\n+`D` deleted\t\t\tFile has been deleted\n+`U` unmerged\t\t\tFile has conflicts after a merge\n+------------------------------------------------------------------------------\n-- \n1.5.2.816.gc5560-dirty\n\n-- \nJonas Fonseca\n"},{"id":"43889","messageId":"20070603171547.GA1965@fieldses.org","threadId":"8402","inReplyTo":"20070602182423.GC19952@diku.dk","subject":"Re: [RFC PATCH] Add git quick reference","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-06-03T17:15:47Z","receivedAt":"2007-06-03T17:15:47Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sat, Jun 02, 2007 at 08:24:23PM +0200, Jonas Fonseca wrote:\n> It attempts to list some of the most commonly used commands, which should\n> give new users an idea of how to get started.\n> \n> Available both as a manpage (generated via a script) and HTML page.\n\nWe have a \"git quick start\" here:\n\n\thttp://www.kernel.org/pub/software/scm/git/docs/user-manual.html#git-quick-start\n\nand there's one on the wiki:\n\n\thttp://git.or.cz/gitwiki/QuickStart\n\nI think the one in the manual tries to follow the organization of the\nmanual more closely.\n\nI haven't tried to compare those two recently, or to compare yours to\neither of them.  If you could compare and suggest any improvements,\nthat'd be helpful.\n\nI like your name better (\"quick reference\" as opposed to \"quick start\").\n\nHaving it as a man page may be a good idea too.  I'd like to keep a copy\nin the manual as well, though, so we'd have to include from some common\nfile.\n\n--b.\n"},{"id":"43999","messageId":"20070604184546.GA27088@diku.dk","threadId":"8402","inReplyTo":"20070603171547.GA1965@fieldses.org","subject":"Re: [RFC PATCH] Add git quick reference","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2007-06-04T18:45:46Z","receivedAt":"2007-06-04T18:45:46Z","isPatch":true,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"J. Bruce Fields <bfields@fieldses.org> wrote Sun, Jun 03, 2007:\n> On Sat, Jun 02, 2007 at 08:24:23PM +0200, Jonas Fonseca wrote:\n> > It attempts to list some of the most commonly used commands, which should\n> > give new users an idea of how to get started.\n> > \n> > Available both as a manpage (generated via a script) and HTML page.\n> \n> We have a \"git quick start\" here:\n> \n> \thttp://www.kernel.org/pub/software/scm/git/docs/user-manual.html#git-quick-start\n> \n> and there's one on the wiki:\n> \n> \thttp://git.or.cz/gitwiki/QuickStart\n> \n> I think the one in the manual tries to follow the organization of the\n> manual more closely.\n\nI like the manual version best. However, it is not as \"visually\" clean\nand simple as I would like, but perhaps this sort of \"use case\" approach\nis better.\n\n> I haven't tried to compare those two recently, or to compare yours to\n> either of them.  If you could compare and suggest any improvements,\n> that'd be helpful.\n\nI will see what I can do when I get the time and courage. :)\n\n> I like your name better (\"quick reference\" as opposed to \"quick start\").\n\nYes, \"quick start\" suggest (at least to me) that it is a tutorial and it\nseems far from that.\n\n> Having it as a man page may be a good idea too.  I'd like to keep a copy\n> in the manual as well, though, so we'd have to include from some common\n> file.\n\nThe main idea was to have the reference in a printable format similar to\nsvn-ref. But the man page was easy to do, although it might not be\nsomething that users would stumble upon.\n\n-- \nJonas Fonseca\n"},{"id":"44185","messageId":"7vps48zuq1.fsf@assigned-by-dhcp.cox.net","threadId":"8402","inReplyTo":"20070604184546.GA27088@diku.dk","subject":"Re: [RFC PATCH] Add git quick reference","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-06-06T20:36:06Z","receivedAt":"2007-06-06T20:36:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonas Fonseca <fonseca@diku.dk> writes:\n\n> J. Bruce Fields <bfields@fieldses.org> wrote Sun, Jun 03, 2007:\n>> On Sat, Jun 02, 2007 at 08:24:23PM +0200, Jonas Fonseca wrote:\n>> > It attempts to list some of the most commonly used commands, which should\n>> > give new users an idea of how to get started.\n>> > \n>> > Available both as a manpage (generated via a script) and HTML page.\n>> \n>> We have a \"git quick start\" here:\n>> \n>> \thttp://www.kernel.org/pub/software/scm/git/docs/user-manual.html#git-quick-start\n>> \n>> and there's one on the wiki:\n>> \n>> \thttp://git.or.cz/gitwiki/QuickStart\n>> \n>> I think the one in the manual tries to follow the organization of the\n>> manual more closely.\n>\n> I like the manual version best. However, it is not as \"visually\" clean\n> and simple as I would like, but perhaps this sort of \"use case\" approach\n> is better.\n>\n>> I haven't tried to compare those two recently, or to compare yours to\n>> either of them.  If you could compare and suggest any improvements,\n>> that'd be helpful.\n>\n> I will see what I can do when I get the time and courage. :)\n>\n>> I like your name better (\"quick reference\" as opposed to \"quick start\").\n>\n> Yes, \"quick start\" suggest (at least to me) that it is a tutorial and it\n> seems far from that.\n\nWhen I started the \"everyday\" document, I wanted to make it a\ncheat sheet usable by people who are not so familiar with the\nworkflow.  The \"quick reference\" would be good for people who\nwant a cheat sheet without need for workflow description.\n"}]}