Differences

This shows you the differences between two versions of the page.

--- devel:git [2010-01-10 11:06] – fixed stable link tracking andi
+++ devel:git [2024-02-06 10:39] (current) – [How to use Git] Web links was checked and updated. Aleksandr
@@ Line 1: / Line 1: @@
 ====== DokuWiki Git Repository ======
-The [[:DokuWiki]] sources are managed through the [[http://git-scm.com/|Git]] version control system.
+The [[:DokuWiki]] sources are managed through the [[http://git-scm.com/|Git]] version control system. Git is a free and open source, distributed version control system designed to handle everything from small to very large projects with speed and efficiency.
-//Git is a free & open source, distributed version control system  designed to handle everything from small to very large projects with speed and efficiency.//
+Git is **NOT** offered as optional version control backend for DokuWiki itself.
-===== How to use git =====
+===== How to use Git =====
 Instead of repeating things that were said elsewhere I just want to give some pointers:
-  * [[http://git-scm.com/download|Download Git]]
+  * [[https://git-scm.com/download|Download Git]]
-  * [[http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html|Official Git Tutorial]]
+  * [[https://git-scm.com/|Git Community]]
-  * [[http://www.kernel.org/pub/software/scm/git/docs/user-manual.html|Git User Manual]]
+  * [[https://schacon.github.io/git/user-manual.html|Git User Manual]]
+  * [[http://contribute.jquery.org/commits-and-pull-requests/|Working with branches: Commits and Pull Requests]] (by jQuery Community)
-===== Using git for DokuWiki =====
+There are also some good books about Git:
+  * [[https://git-scm.com/book/en|Scott Chacon - Pro Git]] (ISBN 978-1-43021-833-3) -- You can read it online **for free** (CC licensed). Translations are also available (e.g. [[https://git-scm.com/book/de|German]]).
+  * [[http://www-cs-students.stanford.edu/~blynn/gitmagic/|Ben Lynn - Git Magic]] (ISBN 978-1-45152-334-8) -- You can read it online **for free** (GPL licensed). Translations are also available (e.g. [[http://www-cs-students.stanford.edu/~blynn/gitmagic/intl/es/|Spanish]]).
+  * [[https://pragprog.com/titles/tsgit/pragmatic-version-control-using-git/|Travis Swicegood - Pragmatic Version Control Using Git]] (ISBN 978-1-93435-615-9)
+  * [[amazon>0596520123|Jon Loeliger - Version Control with Git]] (ISBN 978-0-59652-012-0)
-Before you start using git, you should configure it with your name and email address:
+===== Git Configuration =====
+Before you start using Git, you should configure it with your name and email address:
   git config --global user.name "Your Name Comes Here"
   git config --global user.email you@yourdomain.example.com
+And optionally setup colors and few helpful aliases:
+  git config --global color.ui auto
+  git config --global alias.st status
+  git config --global alias.ci commit
+  git config --global alias.up pull --rebase
+===== Using Git for DokuWiki =====
 To fetch the current development version of DokuWiki use the following command (This creates the directory **dokuwiki** for you):
-  git clone git://github.com/splitbrain/dokuwiki.git
+  git clone git://github.com/dokuwiki/dokuwiki.git
 To update an existing checkout use this command from within the DokuWiki directory:
@@ Line 28: / Line 43: @@
   git pull
-When you create a new source file, use this command to add it to the git repository:
+When you create a new source file, use this command to add it to the Git repository:
   git add somenewfile
-When you changed some already tracked files, you need to tell git about it:
+When you changed some already tracked files, you need to tell Git about it:
   git add --patch
-The ''--patch'' will interactively ask you what parts you want to check in (very much like [[darcs]] behaved)
+The ''<nowiki>--patch</nowiki>'' will interactively ask you what parts you want to check in (very much like [[darcs]] behaved)
 When you're finished with your changes use:
@@ Line 42: / Line 57: @@
   git commit
-This will scan your local git repository to find the changes that have occurred and will locally "commit" your changes so that they are not overwritten by a ''pull''. Unlike CVS it doesn't actually send the files anywhere at this point though. It's more like a "local tag" for your own copy of the code.
+This will scan your local Git repository to find the changes that have occurred and will locally "commit" your changes so that they are not overwritten by a ''pull''. Unlike CVS it doesn't actually send the files anywhere at this point though. It's more like a "local tag" for your own copy of the code.
 To get your changes included in the official tree, create a patchfile:
-  git format-patch
+  git format-patch origin/master
+This creates one (or more) numbered patch files that can be mailed manually to the [[:mailinglist]]. However, this method results in extra manual work for the maintainers of DokuWiki, and makes it difficult to provide feedback on your contribution. So please continue to the section below, and try offering your changes as pull requests.
-This creates one (or more) numbered patch files that can be mailed manually to the [[:mailinglist]].
 ==== Tips and Tricks ====
@@ Line 55: / Line 72: @@
   * Make sure your editor does not change line endings (from Unix LF to DOS CRLF), this would result in a complete file replace, instead of a small patch because each line was changed.
   * Make a patch for a single feature. When you worked on two different features (eg, a language fix and a function update), ''add'' and ''commit'' two patches, with one for each feature. Using the ''--patch'' option for ''add'' makes that easy for you by asking what to include in the patch.
-  * Patches should be sent to the [[:mailinglist]] and you should explain what they do and why.
+  * We **really prefer** [[github|pull requests]], above patches sent to the [[:mailinglist]]. See below for more guiding for a pull request. You should explain what patches do and why.
-  * A web interface to the git repository is available at [[http://github.com/splitbrain/dokuwiki]]
+  * A web interface to the Git repository is available at [[https://github.com/dokuwiki/dokuwiki]]
-==== Mixing the official tree with own patches ====
+===== Use branches and your own fork, for doing pull requests =====
+(Making [[https://github.com/dokuwiki/dokuwiki/pulls|pull requests]] is the preferred manner of contributing)
-FIXME explain branches
+Above explanation mixes your changes with the incoming changes of DokuWiki in the same 'branch', and you cannot publish them directly to  Github because you have (probably) not direct commit access to this repository. Therefore, if your intention is to propose your change a //fork// of the repository at Github is needed, in which you can make //branches// for each issue you like to fix.
-==== Maintaining a stable version with git ====
+First you make at Github your own fork with the 'Fork' button topright on https://github.com/dokuwiki/dokuwiki
-Git isn't only for DokuWiki developers, it can be used to get the latest stable version and to update to the next stable version when it is released. To do so you need to clone the repository but work in the stable branch:
+With the clone url, shown with the 'Code' button, you can fetch your fork on your machine. This create the folder 'dokuwiki':
-  git clone git://github.com/splitbrain/dokuwiki.git
+  git clone git@github.com:YourName/dokuwiki.git
-  git checkout -b stable origin/stable
+Next you add the original DokuWiki repository as extra remote repository:
+  git remote add upstream git://github.com/dokuwiki/dokuwiki.git
+Verification of this addition can done by showing all remotes (origin=your online fork, upstream=original online DokuWiki repo)
+  git remote -v
+If you start making the modifications you like to propose, it is recommended to make first a separate branch in your fork. If your plan is to fix multiple issues (e.g. fix php warnings and add a new feature), please create a branch for each of them. A branch can be created with:
+  git checkout -b yourbranchname
+In this branch you can make your changes. Storing changes in git, goes in two steps: 1) first add the files such that git knows which files are ready, 2) commit the added files.
+  # add an entire file to the coming commit
+  git add your/file.php
+  # or decide interactively which changes in a file to add to the coming commit
+  git add --patch
+After done with adding, commit these changes with
+  git commit
+Advice: try to commit small understandable pieces of code per commit, if the entire change is larger, do not all changes in one commit. This helps later other people that review your proposal :-).
+If you wonder what the status is of your repository during the different steps, you can ask git more info:
+  # shows current status, and gives eventually some hints how to progress
+  git status
+  # show not commit changes
+  git diff
+Switching between branches:
+  git checkout yourbranchname
+  # back to main branch
+  git checkout master
+Sometimes you have changes, which are not yet ready for committing, but you like to switch for example between branches. You can temporary store the not committed changes.
+  # store temporary all not committed changes
+  git stash
+  # if you like to continue, you can reapply the changes
+  git stash apply
+Of course there are regularly changes added to DokuWiki's repository. You can download the history with
+  git fetch upstream
+And next merge them in your branch
+  # go to your branch (if you are not already there)
+  git checkout yourbranchname
+  # merge the changes from the 'master' branch of the 'upstream' repository
+  # in the current branch.
+  git merge upstream/master
+Alternatively, you can do the fetching and merging at once with one pull command:
+  git pull upstream master
+If you are ready, and all your changes are committed, you can publish your branch to your fork on Github
+  git push origin yourbranchname
+On Github, you see now a notice which let you initiate a Pull request to DokuWikis repository. DokuWiki's developers will review your proposal and eventually request some changes.
+Changes can be made locally again in your branch, and committed as before. If done, you can publish them in the same manner as the first time. It will simply sent the extra commits to your fork, and automatically appear in the pull request as well.
+  git push origin yourbranchname
+**Background**:
+  * [[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork|committing changes to a pull request branch created from a fork]]
+  * [[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork|syncing a fork]]
+  * [[https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository|pushing commits to a remote repository]]
+  * https://training.github.com/downloads/github-git-cheat-sheet/
+==== Maintaining a stable version with Git ====
+Git isn't only for DokuWiki developers. It can be used to get the latest stable version and to update to the next stable version when it is released. To do so you need to clone the repository but checkout the stable branch:
+  git clone --branch stable https://github.com/dokuwiki/dokuwiki.git
 Now you can pull all needed updates whenever a new release is made:
+  cd dokuwiki
   git pull
-===== Why Git? =====
-The reasons for a distributed RCS are well explained at [[darcs#Why Darcs?]]. So why did we switch from darcs to git?
+==== Adding plugin/template git repositories in the tree===
+You can checkout your plugin repository (or if contributing to others' plugin, your fork of the plugin) in the tree of the development version. By doing this, it integrates well the [[unittesting|unit tests]] and global Dokuwiki project settings.
+Go to the plugins (or template) folder
+  cd dokuwiki/lib/plugins
+  # or
+  cd dokuwiki/lib/tpl
+Clone the plugin repository, this creates the folder 'dokuwiki-plugin-example'
+  git clone git@github.com:YourName/dokuwiki-plugin-example.git
-While darcs is somewhat more intuitive to use, the differences between both systems aren't very big. Except that git is now much more often used than darcs. In addition, darcs doesn't work very well for larger projects. DokuWiki isn't shrinking and the quirks and slowness of darcs is quite a burden sometimes.
+Rename to the correct base name (if you hesitate, check ''[[devel:plugin_info|plugin.info.txt]]'' or ''[[devel:template_info|template.info.txt]]'')
-Also using a more popular revision control system makes it possible to outsource the hosting to services like github, which means less stuff to administer for us and less traffic on the DokuWiki server.
+  mv dokuwiki-plugin-example example
-A more popular revision control system also makes it easier for new developers and other contributors to participate in the project. If they have to learn a new RCS just to start working on the code, that's a barrier to entry that they may not overcome. (It's amazing how little it takes to keep people from participating!) Smoothing the path a bit for new contributors can improve the quality of the code significantly.
+Eventually, you have to configure your IDE to recognize the repository e.g. in [[devel:intellij_idea#mapping_of_plugin_git_repositories|InteliJ IDEA]].