Help:UsingGit

From Openbox

(Difference between revisions)
Jump to: navigation, search
(Low bandwidth option: mention gitweb snapshots.)
 
(33 intermediate revisions by 12 users not shown)
Line 1: Line 1:
 
__TOC__
 
__TOC__
= Quick Instructions =
+
= Quick instructions =
  
To get up and running, you just need one command.  This will create a directory called <code>openbox</code> and download the git repository into it:
+
The following command will create a directory called "<code>openbox</code>" and download the source code into it (i. e., will create the local copy of external repository):
  
<code>git clone git://git.icculus.org/dana/openbox openbox</code>
+
git clone https://github.com/danakj/openbox openbox
  
To get the latest changes, from inside the downloaded git repository, run
+
The following command will get the latest changes from external repository and store them to the downloaded local repository:
  
<code>git pull</code>
+
git pull
 +
 
 +
Note however that this only does what you expect, if you haven't made any changes. If you have, it will attempt to merge your changes, which may or may not be what you want; see "[[#Local changes|Local changes]]" below.
  
 
= Branches =
 
= Branches =
  
Currently, there are three branches of interest in the Openbox git repos: master, 3.4-working and backport. Master is the branch that will most likely become Openbox 3.5 or so, 3.4-working keeps compatibility with the rc.xml file fron the 3.4.x releases, and backport is where we put fixes and features that should go in both the other branches.
+
There are two main branches in the Openbox git repositories: "'''work'''" and "'''master'''". The difference is that our "work" branches can have testing stuff and be rebased (which means, git will get confused, if you try to pull from them). Once we are pretty sure something will at least not blow up, it will be put on the "master" branch and we try not to rebase that unless really needed.
  
By default you will get the master branch, hence the name. If you want the 3.4-working branch, run
+
By default you will get the "master" branch, hence the name. If you want the "work" branch, the first time you will need to run:
  
<code>git checkout --track -b 3.4-working origin/3.4-working</code>
+
git checkout --track -b work origin/work
  
You can now switch between them with <code>git checkout master</code> and <code>git checkout 3.4-working</code>.
+
or if you have a recent git (somewhere in 1.6.x), you can just do:
  
If you want the very latest changes, first decide if you want 3.4-working or master, then check if we've recently merged the backport branch, for example by checking the output of <code>git-log</code>, looking at <code>gitk --all</code> or at [http://git.icculus.org/?p=dana/openbox.git;a=summary the gitweb interface] (look near the bottom under the "heads" header). If there are any interesting changes in the backport branch you want, just run
+
git checkout -t origin/work
  
<code>git merge origin/backport</code>
+
You can now switch between branches with <code>git checkout master</code> and <code>git checkout work</code>.
  
and git will pull in the changes for you. Note however that a git pull will not remerge backport for you, it will only get updates from the branch you're currently on. If there are new commits on backport just rerun the merge command.
+
If you want the very latest changes, first decide, if you want "master" or "work". For "master" you can usually just run <code>git pull</code>, but if you're on "work", you probably want to run something like:
 +
 
 +
git fetch ; git reset --hard origin/work
 +
 
 +
Note though that this will delete '''all''' local changes to checked out files and also any commits you've made on the current branch. If you do have commits, you can try <code>git pull --rebase</code>, but no guarantees. If something goes wrong, anything you've committed is actually still available, read the <code>git-reflog</code> man page for details. Uncommitted changes will be gone after a reset <code>--hard</code> though.
  
 
= Local changes =
 
= Local changes =
  
Unlike CVS and Subversion, git lets you have local changes while still tracking upstream development, in a nut shell, make your changes and run
+
Unlike CVS and Subversion, git lets you have local changes while still tracking upstream development. In a nut shell, make your changes and run:
  
<code>git commit -a -m "informative message"</code>.
+
git commit -a -m "informative message"
  
It's usually a good idea to keep your changes in a separate branch. You can do this in a couple of ways, the easiest way is to run
+
It's usually a good idea to keep your changes in a separate branch. You can do this in a couple of ways. The easiest way is to run:
  
<code>git checkout -b my-branch master</code>
+
git checkout -b my-branch master
  
then commit all your changes to that branch.
+
and then commit all your changes to that branch.
  
 
== Conflicting changes ==
 
== Conflicting changes ==
  
If you hang on to your changes for a long time, it's likely that we will make commits that conflict with yours. There are two ways to deal with this, you can either git-merge our branch and resolve the differences, but the better way is to use git-rebase. This command will take your commits and apply them to the tip (ie latest version) of the specified branch, pausing after each commit that conflicts. This usually makes it easier to resolve the conflicts and also gives a nicer history. Using git-rebase is a bit complicated so read the man page.
+
If you hang on to your changes for a long time, it's likely that we will make commits, that conflict with yours. There are two ways to deal with this. You can either <code>git-merge</code> our branch and resolve the differences, but the better way is to use <code>git-rebase</code>. Last command will take your commits and apply them to the tip (the latest version) of the specified branch, pausing after each commit that conflicts. This usually makes it easier to resolve the conflicts and also gives a nicer history. Using <code>git-rebase</code> is a bit complicated, so read the man page.
  
If you just want to test that your changes work with the latest version of openbox, you can merge master and then later use <code>git reset --hard HEAD^</code> to revert the merge. However, I recommend first doing a <code>git checkout -b my-temp</code>, since running git reset twice will continue reverting real commits, so it's easy to mess up. If you're doing all the temp merging on a separate branch you don't have to worry about that.
+
If you just want to test that your changes work with the latest version of Openbox, you can merge "master" branch and then later use <code>git reset --hard HEAD^</code> to revert the merge. However, I recommend first doing a <code>git checkout -b my-temp</code>, since running <code>git reset</code> twice will continue reverting real commits, so it's easy to mess up. If you're doing all the temp merging on a separate branch you don't have to worry about that.
  
 
= Contributing code =
 
= Contributing code =
  
You've coded an exciting feature and now you want to send a diff, how to do it? git-diff you might guess, and while that will produce a diff you can send, git-format-patch is a bit nicer as it will automatically give you a patch file per commit that you want to send, with the commit message in each file.
+
== GitHub workflow ==
 +
 
 +
If you'd like to use the GitHub workflow, then make a fork of the Openbox git repo above via [https://github.com GitHub], and send pull requests from your branch with your code changes. GitHub has [https://help.github.com documentation], describing this process.
 +
 
 +
== BugZilla workflow ==
 +
 
 +
You've coded an exciting feature and want to send a diff? How to do it? <code>git diff</code> you might guess, and while that will produce a diff you can send. <code>git format-patch</code> is a bit nicer as it will automatically give you a patch file per commit that you want to send, with the commit message in each file.
 +
 
 +
In the simple case, where you just want to send off the top commit from your repo, do:
 +
 
 +
git format-patch -1
 +
 
 +
If you have a bunch of patches and you have git 1.7 you can do:
 +
 
 +
git format-patch @{u}
 +
 
 +
and it will figure out the correct branch to consider "upstream" and spit out a bunch of patch files. If you don't, you have to give the range manually, but it will almost always be:
  
Another option is to set up your own public repo and simply tell us where to pull your changes from, look at the git-daemon man page for details. You can also use the git-bundle command to send a file that contains all commits, which we can then pull from. For example if you've made all your commits on the branch my-branch which you produced at some point from git checkout -b master, you can produce your bundle with
+
git format-patch origin/master
  
<code>git bundle create my-bundle master..my-branch</code>
+
Once you have your patch(es), open a bug in the bugzilla as instructed [[Openbox:Contribute|here]].
  
then send the file my-bundle to us.
+
Another option is to set up your own public repo and simply tell us where to pull your changes from. Look at the <code>git-daemon</code> man page for details. This is not really preferred usually though, and you'll probably need to be patient and hang around in the [[Openbox:Community_portal|IRC channel]] for a while.
  
 
= Low bandwidth option =
 
= Low bandwidth option =
  
If your internet connection is very slow (the full git repo is currently around 8.5MB) and you just want the very latest version without any history, you can run
+
If your internet connection is very slow (the full git repo is currently around 8.5 MB) and you just want the very latest version without any history, you can run:
  
<code>git clone --depth 1 git://git.icculus.org/dana/openbox openbox</code>
+
git clone --depth 1 https://github.com/danakj/openbox openbox
  
This will give you only the current and preceding commit from each branch, but you can't do much more with your repo than compile the code. Merging as described above will only work if you use a depth high enough to include the point where the backport branch separated from master. See the git-clone and git-fetch man pages for further details.
+
This will give you only the current and preceding commit from each branch, but you can't do much more with your repo than compile the code. Merging as described above will only work, if you use a depth high enough to include the point, where the "backport" branch separated from "master" branch. See the <code>git-clone</code> and <code>git-fetch</code> man pages for further details.
  
You can also download a tarball of any revision via [http://git.icculus.org/?p=dana/openbox.git;a=summary gitweb]. Click "tree" next to a branch name at the bottom, then "snapshot" at the top of the new page.
+
You can also download a tarball of any revision via [http://git.openbox.org/?p=dana/openbox.git;a=summary gitweb]. Click "tree" next to a branch name at the bottom, then click "snapshot" at the top of the new page.
  
 
= Alternate repos =
 
= Alternate repos =
  
Due to the distributed nature of git, you can choose to pull from various upstream locations (see the git-remote man page for details on how to use several remotes).
+
Due to the distributed nature of git, you can choose to pull from various upstream locations (see the <code>git-remote</code> man page for details on how to use several remotes):
  
 
<code>
 
<code>
git://git.icculus.org/dana/openbox<br>
+
git://git.openbox.org/dana/openbox<br/>
git://git.icculus.org/mikachu/openbox<br>
+
git://git.openbox.org/mikachu/openbox<br/>
git://mikachu.ath.cx/openbox.git
+
git://git.mika.l3ib.org/openbox.git<br/>
 +
git://repo.or.cz/openbox.git<br/>
 +
git://github.com/Mikachu/openbox<br/>
 +
git://github.com/danakj/openbox
 
</code>
 
</code>
  
The astute git user will notice that there are some variations in branches offered among these, for example dana has a libs branch that separates out some common wm code in a library, and mikachu has a mikabox branch which is just some crazy stuff.
+
The astute git user will notice, that there are some variations in branches offered among these, for example dana has a "libs" branch that separates out some common wm code in a library, and mikachu has a "mikabox" branch which is just some crazy stuff.
  
 
= Further reading =
 
= Further reading =
  
On the [http://git.or.cz git homepage] there are many great tutorials and all the man pages are available for browsing as well.
+
On the [http://git.or.cz git home page] there are many great tutorials and all the man pages are available for browsing as well.

Latest revision as of 03:42, 10 July 2017

Contents

[edit] Quick instructions

The following command will create a directory called "openbox" and download the source code into it (i. e., will create the local copy of external repository):

git clone https://github.com/danakj/openbox openbox

The following command will get the latest changes from external repository and store them to the downloaded local repository:

git pull

Note however that this only does what you expect, if you haven't made any changes. If you have, it will attempt to merge your changes, which may or may not be what you want; see "Local changes" below.

[edit] Branches

There are two main branches in the Openbox git repositories: "work" and "master". The difference is that our "work" branches can have testing stuff and be rebased (which means, git will get confused, if you try to pull from them). Once we are pretty sure something will at least not blow up, it will be put on the "master" branch and we try not to rebase that unless really needed.

By default you will get the "master" branch, hence the name. If you want the "work" branch, the first time you will need to run:

git checkout --track -b work origin/work

or if you have a recent git (somewhere in 1.6.x), you can just do:

git checkout -t origin/work

You can now switch between branches with git checkout master and git checkout work.

If you want the very latest changes, first decide, if you want "master" or "work". For "master" you can usually just run git pull, but if you're on "work", you probably want to run something like:

git fetch ; git reset --hard origin/work

Note though that this will delete all local changes to checked out files and also any commits you've made on the current branch. If you do have commits, you can try git pull --rebase, but no guarantees. If something goes wrong, anything you've committed is actually still available, read the git-reflog man page for details. Uncommitted changes will be gone after a reset --hard though.

[edit] Local changes

Unlike CVS and Subversion, git lets you have local changes while still tracking upstream development. In a nut shell, make your changes and run:

git commit -a -m "informative message"

It's usually a good idea to keep your changes in a separate branch. You can do this in a couple of ways. The easiest way is to run:

git checkout -b my-branch master

and then commit all your changes to that branch.

[edit] Conflicting changes

If you hang on to your changes for a long time, it's likely that we will make commits, that conflict with yours. There are two ways to deal with this. You can either git-merge our branch and resolve the differences, but the better way is to use git-rebase. Last command will take your commits and apply them to the tip (the latest version) of the specified branch, pausing after each commit that conflicts. This usually makes it easier to resolve the conflicts and also gives a nicer history. Using git-rebase is a bit complicated, so read the man page.

If you just want to test that your changes work with the latest version of Openbox, you can merge "master" branch and then later use git reset --hard HEAD^ to revert the merge. However, I recommend first doing a git checkout -b my-temp, since running git reset twice will continue reverting real commits, so it's easy to mess up. If you're doing all the temp merging on a separate branch you don't have to worry about that.

[edit] Contributing code

[edit] GitHub workflow

If you'd like to use the GitHub workflow, then make a fork of the Openbox git repo above via GitHub, and send pull requests from your branch with your code changes. GitHub has documentation, describing this process.

[edit] BugZilla workflow

You've coded an exciting feature and want to send a diff? How to do it? git diff you might guess, and while that will produce a diff you can send. git format-patch is a bit nicer as it will automatically give you a patch file per commit that you want to send, with the commit message in each file.

In the simple case, where you just want to send off the top commit from your repo, do:

git format-patch -1

If you have a bunch of patches and you have git 1.7 you can do:

git format-patch @{u}

and it will figure out the correct branch to consider "upstream" and spit out a bunch of patch files. If you don't, you have to give the range manually, but it will almost always be:

git format-patch origin/master

Once you have your patch(es), open a bug in the bugzilla as instructed here.

Another option is to set up your own public repo and simply tell us where to pull your changes from. Look at the git-daemon man page for details. This is not really preferred usually though, and you'll probably need to be patient and hang around in the IRC channel for a while.

[edit] Low bandwidth option

If your internet connection is very slow (the full git repo is currently around 8.5 MB) and you just want the very latest version without any history, you can run:

git clone --depth 1 https://github.com/danakj/openbox openbox

This will give you only the current and preceding commit from each branch, but you can't do much more with your repo than compile the code. Merging as described above will only work, if you use a depth high enough to include the point, where the "backport" branch separated from "master" branch. See the git-clone and git-fetch man pages for further details.

You can also download a tarball of any revision via gitweb. Click "tree" next to a branch name at the bottom, then click "snapshot" at the top of the new page.

[edit] Alternate repos

Due to the distributed nature of git, you can choose to pull from various upstream locations (see the git-remote man page for details on how to use several remotes):

git://git.openbox.org/dana/openbox
git://git.openbox.org/mikachu/openbox
git://git.mika.l3ib.org/openbox.git
git://repo.or.cz/openbox.git
git://github.com/Mikachu/openbox
git://github.com/danakj/openbox

The astute git user will notice, that there are some variations in branches offered among these, for example dana has a "libs" branch that separates out some common wm code in a library, and mikachu has a "mikabox" branch which is just some crazy stuff.

[edit] Further reading

On the git home page there are many great tutorials and all the man pages are available for browsing as well.

Personal tools