Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* pu/jg/docs: Update releasenotes, as autorefresh won't make it into 0.7 ReleaseNotes for v0.7 with author information Site: W3C-Valid and CSS/HTML corrections UserManual: Rewrite most parts for GitX 0.7 GitX 0.7 Release-Notes UserManual: Add disclaimer as to what GitX is Conflicts: Site/UserManual/text/01 - Introduction.markdown
- Loading branch information
Showing
19 changed files
with
149 additions
and
79 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,26 @@ | ||
v0.7 | ||
=== | ||
|
||
This feature-release has the following new features and enhancements: | ||
|
||
* Line-wise staging by selecting lines from hunks (JD Smith) | ||
* Discarding hunks/changes to files (using git apply --reverse) (Johannes Gilger) | ||
* Show current HEAD in window-title (Johannes Gilger) | ||
* Show current branch in orange in history view (Steven Michalske) | ||
* Collapse commit-list/diff-view using Command-Shift-Up/Down (Johannes Gilger) | ||
* Sign-Off commits in commit view (Johannes Gilger, Nicolas Riley) | ||
* "Show in Finder" for files in commit view (Charles O'Rourke) | ||
* Commit hooks are executed when committing (Joe Fiorini, Pieter de Bie) | ||
* Branches can be deleted from the UI | ||
|
||
Small enhancements: | ||
|
||
* Show committer name if it differs from authors name (Benjamin Kramer) | ||
* Columns in history view can be toggled (Pieter de Bie) | ||
* Reuse author-information when amending a commit (Pieter de Bie) | ||
* Use modal alerts where possible | ||
* Don't display content of binary-files in tree-view | ||
|
||
In addition a lot of bugs were fixed and numerous tiny features introduced. | ||
|
||
Credits go to: Pieter de Bie, Johannes Gilger, Benjamin Kramer, Nicholas Riley, JD Smith, Joe Fiorini, Dave Grijalva, Charles O'Rourke, Gerd Knops, dbr, Mike Czepiel, Benoit Cerrina, Steven Michalske and Stonewall Ballard |
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,16 +1,18 @@ | ||
User Manual | ||
----------- | ||
|
||
This is the GitX user's manual. In this document, you will be able to read | ||
about everything you need to know on how to use GitX. | ||
This is the GitX user's manual. This document tries to explain the most common used features and explains the concepts that might be confusing if you've never used a git GUI. | ||
|
||
### Disclaimer | ||
|
||
GitX aims to be a graphical wrapper around the most-frequently used | ||
git-commands, enabling you to satisfy your daily git needs in one consistent | ||
program. GitX doesn't aspire to be a complete interface for the wide variety of | ||
git command-line programs with their ever-growing number of options. It's also | ||
no easy way to learn git. A sound understanding of how git stores data, how it | ||
works on that data and how to recover from (accidental) deletion of branches | ||
and commits will not only help you with git but will also enable you to learn | ||
GitX with greater confidence and speed. | ||
program. GitX doesn't aspire to be a complete interface for the wide variety | ||
of git command-line programs with their ever-growing number of options. It's | ||
also no easy way to learn git. A sound understanding of how git stores data, | ||
how it works on that data and how to recover from (accidental) deletion of | ||
branches and commits will not only help you with git but will also enable you | ||
to learn GitX with greater confidence and speed. Since GitX is far from | ||
complete you'll probably still have to use it in conjunction with the | ||
command-line git for more complex tasks, such as merging or performing remote | ||
operations. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,29 +1,62 @@ | ||
### Overview | ||
|
||
![GitX's Open Dialog](images/UserManual/opendialog.png) | ||
When you open GitX for the first time, you will be greeted by an open-dialog. In this dialog, you should select the Git repository you want to open. You can select either a directory containing a .git directory, or a .git directory itself. After doing this, you will be greeted by the default GitX view, which is the history-view. The history-view consists of two main parts. In the top part, there is an overview of all commits in your currently checked out branch. In the bottom part is a detail view that can show you more information about the selected commit. | ||
When you open GitX for the first time, you will be greeted by an open-dialog. In this dialog, you should select the Git | ||
repository you want to open. You can select either a directory containing a .git directory, or a .git directory itself. | ||
After doing this, you will be greeted by the default GitX view, which is the history-view. The history-view consists of | ||
two main parts. The top part is used for displaying commits on branches and the bottom-view displays details about the | ||
selected commit. The window-title will always show you the currently checked-out branch (or indicate a detached HEAD). | ||
|
||
![Menubar](images/UserManual/menubar.png) | ||
The menu contains buttons to switch between history/commit-view, a selector for specifying which branch to show and an | ||
'Add branch' button. Branches can be checked-out and deleted within GitX by right-clicking their colored bubbles the | ||
commit-list. | ||
|
||
You can double-click the divider between these areas to collapse the smaller-one or you can use Command-Shift-Up and | ||
Command-Shift-Down to do so. | ||
|
||
As of GitX 0.7 reloading the view manually should not be necessary anymore. GitX monitors the open repository by default | ||
and automatically reloads itself when it has detected a change. If this is problematic you can deactivate that behaviour | ||
in the _Preferences_. | ||
|
||
#### The commit list | ||
|
||
![History View](images/UserManual/historyview.png) | ||
On the left side in the commit list you can see the _branch lines_. These show you how your history has diverged and merged. As newer commits are on top, two lines joining each other from the bottom is a merge. This way you see which branches were merged in without any effort. | ||
On the left side in the commit list you can see the _branch lines_. These show you how your history has diverged and | ||
merged. As newer commits are on top, two lines joining each other from the bottom is a merge. This way you see which | ||
branches were merged in without any effort. | ||
|
||
On some commits, to the right of the branch lines you will find _commit labels_. These indicate references to these commits, for example branch heads and remote heads. _Green_ labels indicate local branches. _Blue_ labels indicate remote branches (it will be in the form of remote/branch). _Yellow_ labels indicate tags. | ||
![Branches](images/UserManual/branch-lanes.png) | ||
On some commits, to the right of the branch lines you will find _commit labels_. These indicate references to these | ||
commits, for example branch heads and remote heads. _Green_ labels indicate local branches. _Blue_ labels indicate | ||
remote branches (it will be in the form of remote/branch). _Yellow_ labels indicate tags. The _orange_ label indicates | ||
the currently checked-out branch. | ||
|
||
There are three columns, the first showing the commit _subject_ (which is the top line of your commit message), the second the _author name_ and the third the commit date. You can sort on any of these columns. However, if you sort the branch lines will disappear. If you click three times on a row, the sorting will be cancelled and the original overview will be restored, including the branch lines. | ||
There are four columns, the first showing the commit _subject_ (which is the top line of your commit message), the | ||
second the _author name_, the third the commit date and the last showing the abbreviated SHA of the commit. You can sort | ||
on any of these columns. However, if you sort the branch lines will disappear. Repeatedly clicking the row will revert | ||
the ordering and the original order will be restored, including the branch lines. | ||
|
||
In the top right you will also find the search bar. Here you can search on subject, author or hash. If you do this, the branch lines will also disappear. | ||
In the top right you will also find the search bar. Here you can search on subject, author or SHA. If you do this, the | ||
branch lines will also disappear. | ||
|
||
#### The detail view | ||
|
||
![The detail switch controller](images/UserManual/detailswitcher.png "The detail switch controller") | ||
In the bottom part of the history view, you can see the detail view. This part changes every time you select another commit. The detail view can switch between three different parts using the _detail switch controller_. The first one shows information about the current commit in a nice markup and will probably be the view you use most. In this mode, you can see a pretty diff of the commit, and information such as the parent hashes and the author's email address. | ||
|
||
If you right-click on a reference in this view, you can choose to remove them. Be careful with this, there is no undo option! ![Removing a ref](images/UserManual/remove_ref.png "Removing references"). The diff view is created in such a way, that it is possible to select a part of the diff and copy and paste it, for example to paste it online and share it with someone. As this is such a common thing to do, GitX provides a way to do it automatically. If you click on the "Gist it" link, GitX will try to upload your current commit as a _git patch_ to [gist.github.com](http://gist.github.com "Github's gist"). This will use your Github cookie from Safari if it has one -- otherwise it will create an anonymous gist. Because this patch is a proper git patch, others can then simply apply it using 'git am'. For example, if your Gistie id is 14667, someone else can run | ||
|
||
curl gist.github.com/14667.txt | git am | ||
|
||
to apply it to their own repository! | ||
|
||
The second detailed view will show a raw commit text, much like 'git show --pretty=raw' would. The third detailed view is more interesting: it allows you to browse your repository as it was at that time point. This is also where the quicklook button in the bottom right comes in: pressing it while selecting a file that can be QuickLooked (an image, for example), will display it in the same way as the Finder's quicklook. GitX even imitates this behaviour by allowing you to press space to quicklook a file. | ||
Below the list of commits rests the detail view which shows information about the currently selected commit. The detail | ||
view can switch between three different ways of displaying the commit using the three buttoms at the bottom. The first | ||
tab shows information about the current commit in a nice markup and will probably be the view you use most. In this | ||
mode, you can see a pretty diff of the commit, and information such as the parent SHA and the author's email address. | ||
|
||
![The diff display](images/UserManual/display_diff.png "Displaying a diff")The view is pretty much self-explanatory but | ||
it does contain some features which might not be obvious. You can right-click the refs and files to get a context-menu. | ||
The "Gist it" buton will upload the current patch to [gist.github.com](http://gist.github.com "Gist"). This will use | ||
your `github.user` and `github.token` git-config options if those are set. Otherwise it will create an anonymous gist. | ||
Have a look at the _Preferences_ to set options for Gisting your patches. | ||
|
||
The second detailed view will simply show the raw content of the commit, much like `git show --pretty=raw` would. | ||
|
||
The third detailed view is more interesting: It allows you to browse your history in tree-view and export files/trees | ||
from certain commits. To do so, select the commit and then simply drag-and-drop the wanted dir/files from the tree to a | ||
folder in the Finder. This is also where the Quicklook button in the bottom right comes in: pressing it while selecting | ||
a file that can be QuickLooked (an image, for example), will display it in the same way as the Finder's quicklook. GitX | ||
even imitates this behaviour by allowing you to press space to quicklook a file. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,33 +1,50 @@ | ||
### Committing | ||
|
||
![GitX's commit view](images/UserManual/commitview.png "The Commit View") GitX | ||
also has a commit interface. This interface mimicks some of `git gui`'s | ||
functionality, but will be extended in future releases. | ||
![GitX's commit view](images/UserManual/commitview.png "The Commit View") The commit-interface of GitX also consists of | ||
two parts. The top part will show the diff of the currently selected file. The bottom part is a bit more complex. | ||
|
||
This view also consists of two parts. The top part will show the diff of the | ||
currently selected file. The bottom part is a bit more complex. | ||
|
||
On the left you will see changes that are _unstaged_. If you are already used to Git's terminology, you will know what this means. These are the changes that have not been added to the index, and thus also will not be committed. | ||
In the left list you will see files that are _unstaged_. If you are already used to Git's terminology, you will know what | ||
this means. These are the changes that have not been added to the index, and thus also will not be committed. | ||
|
||
The rightmost part shows the _staged changes_. These _will_ be committed in the next commit. | ||
|
||
It is possible to have a filename in both parts at once. In that case, there are some changes in the file that will be committed, and some that have been left out. Clicking on their name will show you what the difference is in the top pane. | ||
It is possible to have a filename in both lists at the same time. In that case, there are some changes in the file that | ||
will be committed, and some that have been left out. Clicking on their name will show you what the difference is in the | ||
top pane. | ||
|
||
To stage a file, double-click on its name. This will move the file from the left to the right. In the same way, you can unstage changes by double clicking on the name in the right pane. If you prefer, you can also drag and drop the files from one list to the other. You can also select multiple files, and then drag them to the other side all at once. | ||
To stage a file, double-click its icon. This will move the file from the left to the right. In the same way, you can | ||
unstage changes by double clicking on the name in the right pane. If you prefer, you can also drag and drop the files | ||
from one list to the other. You can also select multiple files, and then drag them to the other side all at once. | ||
|
||
Every file has an icon associated with it. This shows the status of that file: | ||
|
||
* A _green_ icon indicates there a changes to a file that is already tracked | ||
* A _green_ icon indicates there a changes to a file that is already tracked. | ||
* A _white_ icon indicates a file that is not tracked by Git, but also not ignored. | ||
* A _red_ icon indicates a file that has been deleted. | ||
|
||
#### Partial staging | ||
|
||
Sometimes you have done more than one thing in a file, but would still prefer to create more than one git commit; the more specific the commits, the better, right? In this case, GitX can help you too. Next to each specific change in a file, called a _hunk_, you will see a blue 'stage' button. If you click on this button, only those specific changes will be staged. | ||
Sometimes you have made more than one change to a file, but would still prefer to create more than one git commit; the | ||
more specific the commits, the better, right? This is where hunk and line-wise staging comes in. Next to each specific | ||
change in a file, called a _hunk_, you will see a blue 'Stage' button. If you click on this button, only those specific | ||
changes will be staged. Clicking the 'Discard' button will irreversibly throw away this change, so use it with care! The | ||
confirmation can be silenced using Alt-Click. | ||
|
||
If the hunk isn't specific enough, you can decrease the context size by manipulating the _context slider_. This is the slider in the top right of the commit view; if you pull it to the left, adjacent changes will be pulled together, if you pull it to the right, they will be split off in smaller hunks. That way you can try to split a hunk two and commit just the hunk that you need. | ||
GitX 0.7 introduced a new way of staging lines: Simply drag-select a few of the lines you want to stage/unstage and a | ||
'Stage lines' button will appear next to it. This allows for much finer granularity than the hunks determined by diff. | ||
Double-clicking a line selects the sub-part of this hunk which isn't separated by blank lines. Selecting lines across | ||
hunks is currently not possible. | ||
|
||
#### Committing | ||
|
||
Once you have staged all your changes, you can commit them. Enter a commit message in the center pane, but remember to use proper commit messages: your first line should be a short description of what you have changed, on which you can elaborate below that. Make sure the subject of your commit is short enough to fit in GitX's history view! Pressing the commit button will hopefully convey to you that the commit was successful, and also give you the commit hash. | ||
The 'Amend' checkbox does what `git commit --amend` does: It enables you to amend the commit on the tip of the current branch. Checking 'Amend' will give you the commit-message of mentioned commit and also will display all of the changes the commit introduced as staged in the right-hand pane. You may then stage/unstage further changes, change the commit-message and hit 'Commit'. | ||
Once you have staged all your changes, you can commit them. Supply a commit message in the center pane, but remember to | ||
use proper commit messages: the first line should be a short description of what you have changed followed by an empty | ||
line and a longer description. Make sure the subject of your commit is short enough to fit in GitX's history view! | ||
Pressing the commit button will hopefully convey to you that the commit was successful, and also give you the commit | ||
hash. | ||
|
||
The 'Amend' checkbox represents `git commit --amend`: It enables you to amend the commit on the tip of the current | ||
branch. Checking 'Amend' will give you the commit-message of mentioned commit and also will display all of the changes | ||
the commit introduced as staged in the right-hand pane. You may then stage/unstage further changes, change the | ||
commit-message and hit 'Commit'. | ||
The 'Sign-Off' button adds your signature to the commit which is common practice in a lot of Open-Source projects. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.