Jakub Narebski pointed out that the git-gui blame viewer is not a widely known feature, but is incredibly useful. Part of the issue is advertising. Up until now we haven't even referenced git-gui from within the core Git manual pages, mostly because I just wasn't sure how I wanted to supply git-gui documentation to end-users, or how that documentation should integrate with the core Git documentation. Based upon Jakub's comment that many users may not even know that the gui is available in a stock Git distribution I'm offering up two basic manual pages: git-citool and git-gui. These should offer enough of a starting point for users to identify that the gui exists, and how to start it. Future releases of git-gui may contain their own documentation system available from within a running git-gui. But not today. Signed-off-by: Shawn O. Pearce <spearce@xxxxxxxxxxx> --- From Jakub Narebski <jnareb@xxxxxxxxx>: > It would be nice though to have git-gui(1) man page describing > 'blame' subcommand of git-gui Yes, it would! You might find one below. ;-) Documentation/cmd-list.perl | 2 + Documentation/git-citool.txt | 32 ++++++++++++ Documentation/git-gui.txt | 115 ++++++++++++++++++++++++++++++++++++++++++ git.spec.in | 12 +++-- 4 files changed, 156 insertions(+), 5 deletions(-) create mode 100644 Documentation/git-citool.txt create mode 100644 Documentation/git-gui.txt diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index a181f75..fcea1d7 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -86,6 +86,7 @@ git-check-attr purehelpers git-check-ref-format purehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain +git-citool mainporcelain git-clean mainporcelain git-clone mainporcelain git-commit mainporcelain @@ -111,6 +112,7 @@ git-fsck ancillaryinterrogators git-gc mainporcelain git-get-tar-commit-id ancillaryinterrogators git-grep mainporcelain +git-gui mainporcelain git-hash-object plumbingmanipulators git-http-fetch synchelpers git-http-push synchelpers diff --git a/Documentation/git-citool.txt b/Documentation/git-citool.txt new file mode 100644 index 0000000..5217ab2 --- /dev/null +++ b/Documentation/git-citool.txt @@ -0,0 +1,32 @@ +git-citool(1) +============= + +NAME +---- +git-citool - Graphical alternative to git-commit + +SYNOPSIS +-------- +'git citool' + +DESCRIPTION +----------- +A Tcl/Tk based graphical interface to review modified files, stage +them into the index, enter a commit message and record the new +commit onto the current branch. This interface is an alternative +to the less interactive gitlink:git-commit[1] program. + +git-citool is actually a standard alias for 'git gui citool'. +See gitlink:git-gui[1] for more details. + +Author +------ +Written by Shawn O. Pearce <spearce@xxxxxxxxxxx>. + +Documentation +-------------- +Documentation by Shawn O. Pearce <spearce@xxxxxxxxxxx>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt new file mode 100644 index 0000000..bd613b2 --- /dev/null +++ b/Documentation/git-gui.txt @@ -0,0 +1,115 @@ +git-gui(1) +========== + +NAME +---- +git-gui - A portable graphical interface to Git + +SYNOPSIS +-------- +'git gui' [<command>] [arguments] + +DESCRIPTION +----------- +A Tcl/Tk based graphical user interface to Git. git-gui focuses +on allowing users to make changes to their repository by making +new commits, amending existing ones, creating branches, performing +local merges, and fetching/pushing to remote repositories. + +Unlike gitlink:gitk[1], git-gui focuses on commit generation +and single file annotation, and does not show project history. +It does however supply menu actions to start a gitk session from +within git-gui. + +git-gui is known to work on all popular UNIX systems, Mac OS X, +and Windows (under both Cygwin and MSYS). To the extent possible +OS specific user interface guidelines are followed, making git-gui +a fairly native interface for users. + +COMMANDS +-------- +blame:: + Start a blame viewer on the specified file on the given + version (or working directory if not specified). + +browser:: + Start a tree browser showing all files in the specified + commit (or 'HEAD' by default). Files selected through the + browser are opened in the blame viewer. + +citool:: + Start git-gui and arrange to make exactly one commit before + exiting and returning to the shell. The interface is limited + to only commit actions, slightly reducing the application's + startup time and simplifying the menubar. + +version:: + Display the currently running version of git-gui. + + +Examples +-------- +git gui blame Makefile:: + + Show the contents of the file 'Makefile' in the current + working directory, and provide annotations for both the + original author of each line, and who moved the line to its + current location. The uncommitted file is annotated, and + uncommitted changes (if any) are explicitly attributed to + 'Not Yet Committed'. + +git gui blame v0.99.8 Makefile:: + + Show the contents of 'Makefile' in revision 'v0.99.8' + and provide annotations for each line. Unlike the above + example the file is read from the object database and not + the working directory. + +git gui citool:: + + Make one commit and return to the shell when it is complete. + +git citool:: + + Same as 'git gui citool' (above). + +git gui browser maint:: + + Show a browser for the tree of the 'maint' branch. Files + selected in the browser can be viewed with the internal + blame viewer. + +See Also +-------- +'gitk(1)':: + The git repository browser. Shows branches, commit history + and file differences. gitk is the utility started by + git-gui's Repository Visualize actions. + +Other +----- +git-gui is actually maintained as an independent project, but stable +versions are distributed as part of the Git suite for the convience +of end users. + +A git-gui development repository can be obtained from: + + git clone git://repo.or.cz/git-gui.git + +or + + git clone http://repo.or.cz/r/git-gui.git + +or browsed online at http://repo.or.cz/w/git-gui.git/[]. + +Author +------ +Written by Shawn O. Pearce <spearce@xxxxxxxxxxx>. + +Documentation +-------------- +Documentation by Shawn O. Pearce <spearce@xxxxxxxxxxx>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/git.spec.in b/git.spec.in index b9dc1d5..287057e 100644 --- a/git.spec.in +++ b/git.spec.in @@ -164,11 +164,10 @@ rm -rf $RPM_BUILD_ROOT %{_bindir}/git-gui %{_bindir}/git-citool %{_datadir}/git-gui/ -# Not Yet... -# %{!?_without_docs: %{_mandir}/man1/git-gui.1} -# %{!?_without_docs: %doc Documentation/git-gui.html} -# %{!?_without_docs: %{_mandir}/man1/git-citool.1} -# %{!?_without_docs: %doc Documentation/git-citool.html} +%{!?_without_docs: %{_mandir}/man1/git-gui.1} +%{!?_without_docs: %doc Documentation/git-gui.html} +%{!?_without_docs: %{_mandir}/man1/git-citool.1} +%{!?_without_docs: %doc Documentation/git-citool.html} %files -n gitk %defattr(-,root,root) @@ -188,6 +187,9 @@ rm -rf $RPM_BUILD_ROOT %{!?_without_docs: %doc Documentation/technical} %changelog +* Thu Jun 21 2007 Shawn O. Pearce <spearce@xxxxxxxxxxx> +- Added documentation files for git-gui + * Tue May 13 2007 Quy Tonthat <qtonthat@xxxxxxxxx> - Added lib files for git-gui - Added Documentation/technical (As needed by Git Users Manual) -- 1.5.2.2.1050.g51a8b - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
