gitextensions / gitextensionsdoc

The new Git Extensions Manual repository

Git Extensions Manual

This repository contains the new Git extensions Manual. Feel free to help us improve this manual by sending pull requests or by opening issues.

Refer to the Wiki here: https://github.com/gitextensions/gitextensions/wiki for details on how to update the documentation.

View Online

The current documentation can be viewed here: https://git-extensions-documentation.readthedocs.org/

PDF and other formats can be downloaded here: https://readthedocs.org/projects/git-extensions-documentation/downloads/

Note: Only the HTML format is "supported" (i.e. from the display point of view). Other formats might have layout issues but the content remains the same for all formats, whether or not you build it locally (provided your local clone is up to date).

Build

To generate the documentation, you need to have Sphinx installed: https://www.sphinx-doc.org/en/master/usage/installation.html#windows The following installs and build the GE html documentation for any Python package with PIP included:

• pip install -U sphinx
• sphinx-build -b html -d build/doctrees source build/html

If you have docker installed, you could also generate the documentation using the command in a cmd prompt (or run the file make-html_docker.cmd):

docker run --rm -v %CD%:/docs sphinxdoc/sphinx sphinx-build -b html -d build/doctrees source build/html

HTML

Simply run make-html.cmd. You can also use make-singlehtml.cmd to generate a single HTML file. The make_and_start_Browser.cmd is an alias of make-html.cmd that will open in your default browser the documentation main index.

HTML Help Files

Warning: This format is not completely supported (i.e. you can generate it but we don't guarantee as good a display quality as for HTML).

Download HTML Help Workshop (https://www.microsoft.com/en-us/download/details.aspx?id=21138).

To build the file, use make-HTMLHelp.cmd

PDF

Warning: This format is not completely supported (i.e. you can generate it but we don't guarantee as good a display quality as for HTML).

To use the PDF builder, you'll need to install:

• rst2pdf easy_install rst2pdf
• pil easy_install pil

Also add ,'rst2pdf.pdfbuilder' to the source/conf.py file at the line 28. Then run make.cmd pdf.

Version update

• Set version in source/conf.py
• Create release branch release/x.y (this is the default from the GE About menu for released versions, 'master' for development builds).
• When releasing final, push 'latest' branch to release/x.y commit (this branch is the default when browsing https://git-extensions-documentation.readthedocs.io/).
• Edit versions in https://readthedocs.org/projects/git-extensions-documentation/versions/ (admin privileges needed). Keep relevant versions active.
• Trigger a build for changed versions

gitextensionsdoc's Issues

Documentation suggestions

Some suggested changes to the documentation:

• Consistently "Git Extensions" -> "GitExtensions"
• Use American English instead of British English

General changes in gitextensions/gitextensions#5921

New video documentation

Hi,

I have created 2 videos for latest version of Git Extensions. May be you would like to add it to documentation.

Installation on Windows:
https://youtu.be/WVeMVyr61ro

Initial Configuration:
https://youtu.be/RIIk86xFotY

Regards,
Ankit

Apply stashed changes after successful checkout (stash will be popped automatically)

New setting Advanced -> Confirmations -> Apply stashed changes after successful checkout (stash will be popped automatically).
It is similar to Apply stashed changes after successful pull. When you checkout branch and choose to stash local changes, they will be automatically poped after successful checkout.

GitExtensionsDoc Workflow

The workflow for Git Extensions code repo is as follows (as per @jbialobr )

Currently the workflow is:
1. Development code should be commited to feature/XXX branch (where XXX is feature short name).
2. Features are merged to master after tests and reviews.
3. When we decide to do a next major release then there is created release/X.yy branch based on master. From this point to release/X.yy we commit only bug fixes.
4. Branch release/X.yy always can be merged to master and should be merged frequently.

What do you think of the following for the Doc repo setup/workflow?

1. the 'master' and 'latest' branches always exist. The official RTD doco is always built from 'latest' branch.
2. updates to documentation for the currently released version of software are first merged to 'latest', then 'master'.
3. changes to documentation for upcoming releases are handled as follows:
   a) if developer is ok with updating doco for their feature, create same feature/XXX branch in Doc repo (branching off from 'latest') and update.
   b) if developer does not create their own doco, then once feature is completed (but not yet merged into code repo 'master') an Issue is raised in the Doc repo that details what the feature implements so somebody can update the documentation to reflect the feature. A feature/XXX branch is created in the Doc repo.
4. Once both code and documentation are complete, they can both be merged into their respective repos 'master' branches.
5. When it is decided to do the next major release, create release/X.yy branch in code repo. In Doc repo, merge 'master' branch into 'latest' branch which will automatically update RTD. Possibly create a 'tag' in Doc repo 'master' branch identifying the major release commit.
6. From then on, bug fixes for a release (that affect documentation) are handled as per point 2 above.

I believe the above will always keep the doco in sync with the software. In the case where you have developers updating code (and you want to do a new release of software) but there is nobody available to do the documentation, then if you at least have Issues raised that detail the documentation changes required it will be easier for somebody to pick up and do.

At the moment, I have found that because the doco is a bit behind the actual released code, I am comparing the application screens/functionality against the documentation to try and work out what documentation needs updating. If there were a list of Issues, then you would know exactly what needs changing without trying to work it out.

Settings chapter

I've opened this issue for questions I have about the GitExt settings while updating the documentation on that chapter.

Q1: I have inquired from @jbialobr regarding changing settings while the radio button "Effective" is selected. Janusz replied with the following including an example:

GitExt looks for the lowest, unset level on which the setting can be set to become effective when a read is performed. If there is no such level, then the Local one is chosen. The Distributed level isn't considered here, because it is treated specially and settings can be set on this level only by a direct assignment.
The levels come in the order (from the lowest to the highest): Global for all repositories, Distributed with the current repository, Local for the current repository.
Settings that are shared with git, like "user name" don't have the "Distributed with the current repository" level.
To give an example, let's say you want to set your user name. When you type it on the Effective level, then three cases may occur:

1. The setting isn't set on any level. In this case the setting will be set on the Global level.
2. The setting is set on the Global level and isn't set on the Local level. In this case the setting will be set on the Local level.
3. The setting is set on the Local level (no matter if there is an entry for the global level). In this case the setting will overwrite the setting on the Local level.

In my testing, case 2 did not work as stated. When I changed my email or user name in the Git Config while "Effective" was selected, the change was saved to the global config file in my user folder and not in the local .git\config file.

I wonder, is it actually working as intended or if it is malfunctioning?

Assuming that it is working as intended, then could the behaviour be summarised instead as:

"GitExt looks for the highest level on which the setting is currently set"

and therefore, in my test, the user name and email were global settings with no local setting so changing the setting while on the "Effective" level saved to the global settings.

latest branch must be moved to release/2.51

http://git-extensions-documentation.readthedocs.io/en/latest/git_extensions.html now points to 2.50

Anchor to each setting

We often have to point users to some particular setting. What do you think about adding anchor to each setting like that:

http://gitextdoco.readthedocs.io/en/latest/settings.html#git-extensions-behaviour-open-last-repo

Version Bump

Released version is 2.51.05 and 3.0 is coming.

Update Jenkins plugin description https://github.com/gitextensions/gitextensions/issues/4202

Revision links

gitextensions/gitextensions#1875

Build server integration (TeamCity implemented already)

gitextensions/gitextensions#1699

Multilingual?

Hello,

Is multilingual possible?

Would translate it to Polish, to complete full Polish Git Extensions' localization. It would be nice way to spread git around Poles.

Greetings

ShellExtensionSettingsPage: add simple preview for context menu items

gitextensions/gitextensions#1661

I don't see simplified Chinese in the Settings

I sea documentation have simplified Chinese

but I don't see it in the Settings

Unable to install "GitExtensions" in Red Hat Enterprise Linux Server release 7.9 (Maipo)

Hi Team,

I am unable to install "GitExtensions - v3.5.1" in Red Hat Enterprise Linux Server release 7.9 (Maipo)
Kindly help me on the same.

Thanks & Regards
Pankaj Jadhav

Incorrect "latest" version resolution

Current:

https://git-extensions-documentation.readthedocs.io/ resolves to https://git-extensions-documentation.readthedocs.io/en/release-3.4/.
However https://git-extensions-documentation.readthedocs.io/en/latest/ resolves to https://git-extensions-documentation.readthedocs.io/en/release-3.3/

Expected:

However https://git-extensions-documentation.readthedocs.io/en/latest/ resolves to the current latest version.

"Download Open Office dictionaries" link is broken

Page Spelling -> link "Download Open Office dictionaries" is broken:

Document how stage selected lines

RTD Official documentation project - incorrect setting?

Just had a look at the official RTD link: https://readthedocs.org/projects/git-extensions-documentation/

I noticed that the "'latest' version" setting is set to 'lastest' ie

Not sure if the auto build will work?

@spdr870 needs to change "lastest" to "latest".

Download url

It would be nice to add URLs to download page and to https://github.com/gitextensions/GitExtensionsDoc

Browse Repository (Chapter 3)

I am starting to update this chapter.

Any questions I have will be posted here.

Create section about Linux and mono

Should the fact that Git Extensions also runs on Linux should be promoted more (e. g. by adding a section to the user manual)? On http://git-scm.com/downloads/guis GitExt is still listed as Windows only.

Discussion: Getting Started (Chapter 2)

I am working on updating this chapter. I have opened this issue so I can ask questions/get answers about my updates to this chapter.

My main focus at the moment is the Settings section (which does not explain all the possible settings on each branch of the settings 'tree' - the current images show tabs for settings - I assume this was changed between version 2.43 and 2.44 to go from tabs to the 'tree' structure).

Currently there is a mixture of screen prints/tables to show/describe the settings. To cut down on the number of screen prints, I propose that this section is changed to

• have one screen print at the start of the Settings section which shows the initial screen displayed when you select Settings/Settings from the menu (i.e. you see the 'tree' of all settings on the left, and the Checklist on the right).
• have subsections with headings Checklist, Git, Git Extensions etc., that within them have a table describing all of the available settings for the particular category .

Is this acceptable or would you prefer screen prints that shows each set of settings? Having less screen prints has the advantages:

• the git repo not storing binary data files (which it isn't very good at!)
• when new releases of software have new settings, only a text table needs updating; no screen prints need to be done.

Note: for the Advanced and Plugins entries in the 'tree', I would probably have screen prints showing what the Settings screen looks like when they are expanded.

While going through the settings, there are some that are not documented and that I have no idea what they do e.g. the Git Extensions setting "Use patience diff algorithm".
I will post a list of these settings that I need a description for - hopefully somebody can explain what they do!

Update the documentation regarding "Commit dialog settings"

• There is a new commit dialog page (see gitextensions/gitextensions#2046)
• Two settings from the "Git Extensions" page have been moved to this new page (see gitextensions/gitextensions#2048)

Installation (Mac) update

I installed Git Extensions on osx using the information in the manual. I needed to take a few extra steps before the application was able to start and I could scroll through the history. There are still some stability issues (I am not able to commit at the moment).

I think it is nice to add these extra steps tot the installation (mac) section of the manual:

Before step 1: install git from http://git-scm/download/mac
After step 7: If you gitextensions crashes with and exception that a font is missing (generic sans serif), you probably can fix this by installing xquartz. This is a version of the X.Org X Windows System that runs on OS X. I am not sure what the side effects are. This can be installed from here: http://xquartz.macosforge.org/landing/
After step 7(2): If gitextensions still crashes because it is unable to load a plugin, empty the plugins folder.

I didn't add this info to the manual myself because I have very little experience on osx. Maybe someone can review this information.

There are empty pages in the generated pdf

The pdf build has some empty pages in it.

Add configuration option to specify a default clone destination directory

gitextensions/gitextensions#1878

Chocolatey and KDiff3

https://github.com/gitextensions/gitextensions/wiki/Application-Dependencies#git
This article recommends users to use Chocolatey to update KDiff3. Meanwhile the KDiff3 package available there is from 2015, and terribly outdated. I'm not really sure what prevented you from using direct official link (https://download.kde.org/stable/kdiff3/) instead of advertising low quality package managers.

Remote feature

The remote features are maybe one of the most used one and the doc is quite old. Moreover the part concerning GitHub might have changed. There's even a GitHub plugin but I don't the doc about it. (When I launch mine, it tells me I already have a key, but I don't really want to delete it because I'm not sure to be able to configure it again 😊)

So I can help but I don't remember how I configured my install (I even think I used GitHub application to do the push/pull during a moment).

Manual link moved

The link to the documentation is bad on several pages, it points to https://git-extensions-documentation.readthedocs.io/en/latest/ which returns a 404 error. Modifying it for https://git-extensions-documentation.readthedocs.io/ would be enough to point to the latest version.

I have seen the wrong link on the following pages:

• at the top of http://gitextensions.github.io/
• in Useful links in the readme of https://github.com/gitextensions/gitextensions#useful-links

Thanks for the great work !

Extract Settings to its own chapter

The detail in the documentation for the settings for Git Extensions is growing and Git Extensions is gaining more settings. I suggest that separating Settings to its own chapter would keep the Getting Started chapter at a more manageable size for new users. It would also provide ample space for writers to add as much detail as possible about the settings without feeling that they are making the Getting Started chapter too large.

User guide for Korean newbies

Hello, This is a Korean user of your application.
Since i started to use Git I learned to use Git Extensions. It was really helpful!
I wanted to teach my classmates how to use Git Extensions since they didn't know about version control systems.
So I made myself a documentation about how to clone, commit and push with Git Extensions and taught my classmates with it.
and I thought it might be helpful for Korean users who just started using Git Extensions.
So I'm sharing my doc link here. thank you!

https://semihumanbeing.oopy.io/d61d2ba6-b484-442c-93c0-48e3d88aba63

On the Browse Repository page, the word Single is misspelled.

On the Browse Repository page http://git-extensions-documentation.readthedocs.io/en/release-2.51/browse_repository.html, the following heading is incorrect:

Singe file history

It should be:

Single file history

Fix images in docs for getting_started

The links under Settings:

Git must be installed prior to starting Git Extensions:
.. image:: /images/install/git_missing.png

First selection is language (depends on the installed languages):
.. image:: /images/install/language.png

Does not work. They should be:

Git must be installed prior to starting Git Extensions:

.. image:: /images/install/git_missing.png

First selection is language (depends on the installed languages):

.. image:: /images/install/language.png

With the blank line before to be able to read the images. Tested it locally and works with building the docs + images do show.

Update settings for https://github.com/gitextensions/gitextensions/pull/4297

Update the settings chapter.

Add a new chapter describing Plugins

Add a new chapter to the documentation describing the available plugins in more detail ie

• what they do
• what dialogs they display/interactions the user has with them.

This change will apply to the currently released documentation.