[Debian Wiki] Update of "BOINC/Development/GitUsage" by NataliaNikitina

[Debian Wiki]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Debian Wiki" for change notification.

The "BOINC/Development/GitUsage" page has been changed by NataliaNikitina:
https://wiki.debian.org/BOINC/Development/GitUsage?action=diff&rev1=66&rev2=67

Comment:
Moved the sections "Typical workflow in git development" and "Get updates in" forward to follow the reader's logic better

  }}}
  is a one line version of the prior manual creation of the Debian-associated packages. (Many thanks go to Guido for pointing this out.) Just, we have not been using the pristine-tar branch anymore for a couple of releases. Hence, feel free to 'git branch -d pristine-tar' if that pops in the 'git branch' list.
  
+ == Typical workflow in git development ==
+ 
+ The ''branch'' is the central theme in git development. They are
+ even created for some very quick local idea, just in case that that development may be in parallel to another idea. In short, a branch is some piece of development that one may accept or reject as a whole. It should be treated a bit like as if those changes done to a branch would be meant to get together as a single patch file.
+ 
+ There are local branches (your ideas) and remote branches (someone else's ideas or collaborative branches like the remote upstream or the remote master branch. 
+ 
+ === Working with local branches ===
+ 
+ Every new idea worked at under git is prepared as a separate branch. This may for instance be a bug that is fixed. When implementing something locally you want to
+  1. create a new branch {{{
+ git branch new_unique_branchname
+ }}}
+  2. check out that branch {{{
+ git checkout new_unique_branchname
+ }}}
+  3. implement your change {{{
+ echo "new stuff" >> "some_file"
+ }}}
+  4. commit change to git {{{
+ git commit "some_file"
+ }}}
+  5. when completed the work or tired of it, check out master branch again {{{
+ git checkout master
+ }}}
+  6. if you have a new idea, go to 1.
+  7. if you want to continue with your development work, go to 2.
+  8. combine your local development with your local mirror of a collaborative branch {{{
+ git merge new_unique_branchname
+ }}}
+  9. (optional) delete that branch you have developed in {{{
+ git branch -d new_unique_branchname
+ }}}
+ 
+ The local master branch is now "ahead of 1 commit" of the origin/master branch, i.e. the branch on the remote server that the master branch was cloned from.
+ 
+ If the idea of yours that is represented by the branch would be generally applicable, then merge it from multiple branches, i.e. from debian/etch and debian/sarge, prior to deleting it.
+ 
+ === Uploading local changes to the servers ===
+ 
+ If one is truly happy about the local master branch, then those local changes should become available to the others: {{{
+ git push
+ }}}
+ If you do not have upload permissions then you can alternatively say {{{
+ git format-patch
+ }}}
+ to have patch files created with your name as an author. For a more anonymous kind of contribution, just show how your debian folder differs from the version of that branch "master" from the same branch on the server referred to as origin (the alioth git repo), try {{{
+ git diff origin debian
+ }}}
+ and send it to the list. The {{{
+ git diff
+ }}} command without the notion of the origin would ask for changes compared to the last committed version, i.e. the latest version locally known to git, not to the latest version on the server.
+ 
+ === New remote branches ===
+ 
+ The branches currently existing on the servers seem sufficient. If you are a not a regular contributor, and even if you are, please consider to discuss the preparation of new branches with Rene and/or possibly Thomas. The idea previously prepared is then merged with the local representation of the server's branches. To have your branch on the remote site, just be a bit more explicit to ''push'': {{{
+ git push origin new_unique_branchname
+ }}}
+ To remove that remote one, use the following (not truly intuitive) syntax: {{{
+ git push origin :new_unique_branchname
+ git branch -d new_unique_branchname
+ }}}
+ So, one needs to perform the removal of a remote branch both on the remote and the local site.
+ 
+ === Committed everything changed but there are still changes ===
+ 
+ This is mightily annoying, but the build process at times changes files that are part of the upstream source tree but nonetheless changed by the build process. Those problems are to be helped by improving the source distribution (e.g. by removing the config.* files) but does this all work without version.h being at least existing?
+ 
+ Changes to those collaterally modified files should not be committed. When git does not allow you to do anything (like uploading a new upstream) then consider running "git reset --hard" or (more intuitively) changes those files back via {{{
+ git diff | patch -p1 -R
+ }}}
+ The latter won't work for changed file permissions (hey, who opts at patching patch for that?) but it is not so bad and the rest can be helped by some "git diff | grep ^diff | cut -f3 -d" " | xargs -r chmod " magic.
+ 
+ == Get updates in ==
+ 
+ For me to understand how git works I keep thinking about it as a collection of patches to some common seed version. That seed can be empty. Every commit of mine produces a new such patch. When another repository wants to profit from my work, then it needs to take my
+ commits/patches and curate those into their latest version. When there is a change required to do so, then this creates another patch on top of the curated-in (aka merged) patches.
+ 
+ So, the inclusion of remotely created work takes two steps / commands:
+  1. ''git fetch'' - get all that you can from some other repository (or the one that was cloned from by default). The fetched patches are then locally available in the branches like 'origin/master' or 'origin/upstream' but not yet seen when checking out the local 'master' or 'upstream' branch. And one cannot change into the 'origin/*' branches directly, or more correctly, you can, but this does not fit here.
+  2. ''git merge origin'' - take all the patches that some branch has but the local branch has not and apply them. The default is to merge from the branch with the same name of that other repository.
+ 
+ The presumably typical learning curve goes like: "git fetch; git merge" is too tedious, I should be using "git pull" instead, which does the same thing but fetches and merges everything with the same name. And then one has somewhen merged bits that one did not intend to merge as of yet and then goes back to "git fetch; git merge" again.
+ 
  == Upstream and the Upstream branch ==
  
  "Upstream" is what was available before Debian packaging started. This is typically a tarball from the software developers' web pages. With BOINC, it is slightly different. 
@@ -204, +288 @@

  
  <<Anchor(TrackingUpstream)>>
  
- == Typical workflow in git development ==
- 
- The ''branch'' is the central theme in git development. They are
- even created for some very quick local idea, just in case that that development may be in parallel to another idea. In short, a branch is some piece of development that one may accept or reject as a whole. It should be treated a bit like as if those changes done to a branch would be meant to get together as a single patch file.
- 
- There are local branches (your ideas) and remote branches (someone else's ideas or collaborative branches like the remote upstream or the remote master branch. 
- 
- === Working with local branches ===
- 
- Every new idea worked at under git is prepared as a separate branch. This may for instance be a bug that is fixed. When implementing something locally you want to
-  1. create a new branch {{{
- git branch new_unique_branchname
- }}}
-  2. check out that branch {{{
- git checkout new_unique_branchname
- }}}
-  3. implement your change {{{
- echo "new stuff" >> "some_file"
- }}}
-  4. commit change to git {{{
- git commit "some_file"
- }}}
-  5. when completed the work or tired of it, check out master branch again {{{
- git checkout master
- }}}
-  6. if you have a new idea, go to 1.
-  7. if you want to continue with your development work, go to 2.
-  8. combine your local development with your local mirror of a collaborative branch {{{
- git merge new_unique_branchname
- }}}
-  9. (optional) delete that branch you have developed in {{{
- git branch -d new_unique_branchname
- }}}
- 
- The local master branch is now "ahead of 1 commit" of the origin/master branch, i.e. the branch on the remote server that the master branch was cloned from.
- 
- If the idea of yours that is represented by the branch would be generally applicable, then merge it from multiple branches, i.e. from debian/etch and debian/sarge, prior to deleting it.
- 
- === Uploading local changes to the servers ===
- 
- If one is truly happy about the local master branch, then those local changes should become available to the others: {{{
- git push
- }}}
- If you do not have upload permissions then you can alternatively say {{{
- git format-patch
- }}}
- to have patch files created with your name as an author. For a more anonymous kind of contribution, just show how your debian folder differs from the version of that branch "master" from the same branch on the server referred to as origin (the alioth git repo), try {{{
- git diff origin debian
- }}}
- and send it to the list. The {{{
- git diff
- }}} command without the notion of the origin would ask for changes compared to the last committed version, i.e. the latest version locally known to git, not to the latest version on the server.
- 
- === New remote branches ===
- 
- The branches currently existing on the servers seem sufficient. If you are a not a regular contributor, and even if you are, please consider to discuss the preparation of new branches with Rene and/or possibly Thomas. The idea previously prepared is then merged with the local representation of the server's branches. To have your branch on the remote site, just be a bit more explicit to ''push'': {{{
- git push origin new_unique_branchname
- }}}
- To remove that remote one, use the following (not truly intuitive) syntax: {{{
- git push origin :new_unique_branchname
- git branch -d new_unique_branchname
- }}}
- So, one needs to perform the removal of a remote branch both on the remote and the local site.
- 
- === Committed everything changed but there are still changes ===
- 
- This is mightily annoying, but the build process at times changes files that are part of the upstream source tree but nonetheless changed by the build process. Those problems are to be helped by improving the source distribution (e.g. by removing the config.* files) but does this all work without version.h being at least existing?
- 
- Changes to those collaterally modified files should not be committed. When git does not allow you to do anything (like uploading a new upstream) then consider running "git reset --hard" or (more intuitively) changes those files back via {{{
- git diff | patch -p1 -R
- }}}
- The latter won't work for changed file permissions (hey, who opts at patching patch for that?) but it is not so bad and the rest can be helped by some "git diff | grep ^diff | cut -f3 -d" " | xargs -r chmod " magic.
- 
- == Get updates in ==
- 
- For me to understand how git works I keep thinking about it as a collection of patches to some common seed version. That seed can be empty. Every commit of mine produces a new such patch. When another repository wants to profit from my work, then it needs to take my
- commits/patches and curate those into their latest version. When there is a change required to do so, then this creates another patch on top of the curated-in (aka merged) patches.
- 
- So, the inclusion of remotely created work takes two steps / commands:
-  1. ''git fetch'' - get all that you can from some other repository (or the one that was cloned from by default). The fetched patches are then locally available in the branches like 'origin/master' or 'origin/upstream' but not yet seen when checking out the local 'master' or 'upstream' branch. And one cannot change into the 'origin/*' branches directly, or more correctly, you can, but this does not fit here.
-  2. ''git merge origin'' - take all the patches that some branch has but the local branch has not and apply them. The default is to merge from the branch with the same name of that other repository.
- 
- The presumably typical learning curve goes like: "git fetch; git merge" is too tedious, I should be using "git pull" instead, which does the same thing but fetches and merges everything with the same name. And then one has somewhen merged bits that one did not intend to merge as of yet and then goes back to "git fetch; git merge" again.
- 
  == Don't do this but interesting to know ==
  
  This tutorial is still evolving, and I am afraid it stops here for now. The following tidbits still need to find their place.