Development/Git/Recipes: Difference between revisions

From KDE TechBase
m (→‎Cloning a Repository: no longer works in 2019)
 
(18 intermediate revisions by 3 users not shown)
Line 2: Line 2:


Brief recipes for common use cases.
Brief recipes for common use cases.
=== Cloning a Repository ===
To clone a local copy of a KDE Git repository, find the repository on http://projects.kde.org/projects  (which no longer works in 2019)  , choose the project, choose the Repository tab and copy the git clone command displayed:
git clone git://anongit.kde.org/<repository-name>
Note this clone will be read-only and you will not be able to push from it.
Alternatively, if you have the standard [[Development/Git/Configuration|KDE Git configuration]] and know the name of the repository simply do:
git clone kde:<repository-name>
This will automatically set the repository up to have push access.


=== Working with existing remote branches ===
=== Working with existing remote branches ===


Remote branches are branches created on the main KDE repository.  These may be a stable branch that you need to do bugfixes on, i.e. the 4.6 release, or a feature branch based on master.
Remote branches are branches created on the main KDE repository.  These may be a stable branch that you need to do bugfixes on, i.e. the 4.6 release, or a feature branch based on master.
To see what local and remote branches exist:
git branch -a


Create a local branch that tracks a remote branch:
Create a local branch that tracks a remote branch:
Line 11: Line 28:
  git checkout <local-branch>
  git checkout <local-branch>


When you want to add your commits to the local branch, first update your local to the current remote state, then push your commits:
When you want to add your commits to the remote branch, first update your local to the current remote state, then push your commits:
  git pull --rebase
  git pull --rebase
  git push origin <local-branch>:<remote-branch>
  git push origin <local-branch>:<remote-branch>
Line 17: Line 34:
=== Working with stable branches ===
=== Working with stable branches ===


For kdelibs, kdepimlibs, kde-runtime, kate, konsole and kde-workspace, the remote stable branches are named as follows:
The remote stable branches are named as follows:


  origin/KDE/4.6
  origin/KDE/4.6


For these modules, to set up a local stable branch to track the remote stable branch:
To set up a local stable branch to track the remote stable branch:


  git branch --track KDE/4.6 origin/KDE/4.6
  git branch --track KDE/4.6 origin/KDE/4.6
Line 30: Line 47:
  git push origin KDE/4.6:KDE/4.6
  git push origin KDE/4.6:KDE/4.6


In other projects the remote stable branches are named as follows:
=== Creating / Deleting Remote Branches ===


origin/4.6
To create a new remote branch simply push your current branch to it:


For these modules, to set up a local stable branch to track the remote stable branch:
git push origin <local-branch>:<remote-branch>


git branch --track 4.6 origin/4.6
To delete a remote branch is a little obscure:
git checkout 4.6


To then push changes to the remote stable branch:
git push origin :<remote-branch>


git push origin 4.6:4.6
=== Tracking Branches ===


=== Creating / Deleting Remote Branches ===
To create a new branch that tracks an existing local or remote branch:


To create a new remote branch simply push your current branch to it:
git branch --track <new-branch> <existing-branch>


git push origin <local-branch>:<remote-branch>
To change the branch the current branch is tracking to a different local or remote branch:


To delete a remote branch is a little obscure:
git branch --set-upstream <existing-branch> <new-upstream-branch>


git push origin :<remote-branch>
=== Cherry Picking ===


=== Cherry Picking ===
Cherry picking is a way to copy a single commit from any local or remote branch to your current local branch.  You can even add ''any'' remote repository you want to your local clone to cherry-pick from.


Cherry picking is a way to copy a single commit from one branch to another.
git cherry-pick <original-commit>


When cherry picking between stable and unstable branches, use the following form:
When cherry picking between stable and unstable branches, ''always'' use the following form:


  git cherry-pick -e -x <original-commit>
  git cherry-pick -e -x <original-commit>


==== Common Options ====
Common Options:


'''-e''' will allow you to edit the commit message to add any extra details and to change the BUG/CCBUG/FIXED-IN messages.
'''-e''' will allow you to edit the commit message to add any extra details and to change the BUG/CCBUG/FIXED-IN messages.
Line 67: Line 83:
'''-x''' will automatically add the original commit number to the end of the commit message to enable better tracing and to simplify merging.  Only do this if the original commit was already published in a public repository, e.g. your are forward porting or back porting the patch.
'''-x''' will automatically add the original commit number to the end of the commit message to enable better tracing and to simplify merging.  Only do this if the original commit was already published in a public repository, e.g. your are forward porting or back porting the patch.


'''-n''' will cherry-pick the changes but not commit them to the new branch.  This is very use full if you need to do further work on a commit.
'''-n''' will cherry-pick the changes but not commit them to the new branch.  This is very useful if you need to do further work on a commit.
 
=== Interactive Rebasing ===
 
If you have many commits in a branch that you want to clean up before pushing to the central repository, then you can use interactive rebasing to merge, split, delete, re-order or edit them.
 
To work with all commits to a branch:
 
git rebase -i <parent-branch>
 
where <parent-branch> is the branch you want to rebase onto.  This is usually the branch that you based the original local branch off or are remotely tracking, but can be any branch you want.
 
To work with just the last n commits you made to a branch:
 
git rebase -i HEAD^n
 
HEAD^ is the terminology for saying "commit prior to head". HEAD~ works too. HEAD^^ would indicate 2 commits back, and so forth.
 
See http://book.git-scm.com/4_interactive_rebasing.html for full details.
 
=== Viewing What You've Changed ===
 
To see the difference between your tracked but unstaged changes and the current branch (including your not-yet-pushed commits)
 
git diff
git diff <filename>
 
To see the difference between your staged changes and the current branch (including your not-yet-pushed commits):
 
git diff --staged
git diff --staged <filename>
 
To see a list of commits to a branch:
 
git log
 
To see the details and diff for a commit
 
git show <commit>
 
=== Stashing Changes ===
 
If you have changes you don't wish to commit but don't want to lose either while you do something else, you can temporarily 'stash' the changes away.  This could be some frequently used debug code,or just some work in progress you need to move to another branch without committing.  If the code is just WIP for the current branch we recommend using an interim commit instead.
 
The stash is a temporary store that holds a stack of uncommitted changes at a repository level.  Commands given below work by default with the stash at the top of the stack, or you can optionally provide the stack reference.
 
To store your current changes at the top of the stash stack:
 
git stash <optional comment>
 
For example:
 
git stash "My debug code"
 
To see all your stashed items in the stash stack:
 
git stash list
 
This will show something like:
 
stash@{0}: WIP on master: 6ebd0e2... My debug code
stash@{1}: WIP on master: 9cc0589... My stashed changes
 
To see the details of an individual stash:
 
git stash show <optional stash ref>
 
To see the stash at the top of the stack:
 
git stash show
 
To see the second item from top:
 
git stash show stash@{1}
 
To restore a stash while keeping a copy in the stack:
 
git stash apply <optional stash ref>
 
To restore a stash and remove it from the stack:
 
git stash pop <optional stash ref>
 
To remove a single stash from the stack without applying it:
 
git stash drop <optional stash ref>
 
To clear out your entire stash stack:
 
git stash clear
 
For more details see:
 
http://www.kernel.org/pub/software/scm/git/docs/git-stash.html
http://book.git-scm.com/4_stashing.html

Latest revision as of 07:13, 11 March 2019

Git Recipes

Brief recipes for common use cases.

Cloning a Repository

To clone a local copy of a KDE Git repository, find the repository on http://projects.kde.org/projects (which no longer works in 2019) , choose the project, choose the Repository tab and copy the git clone command displayed:

git clone git://anongit.kde.org/<repository-name>

Note this clone will be read-only and you will not be able to push from it.

Alternatively, if you have the standard KDE Git configuration and know the name of the repository simply do:

git clone kde:<repository-name>

This will automatically set the repository up to have push access.

Working with existing remote branches

Remote branches are branches created on the main KDE repository. These may be a stable branch that you need to do bugfixes on, i.e. the 4.6 release, or a feature branch based on master.

To see what local and remote branches exist:

git branch -a

Create a local branch that tracks a remote branch:

git branch --track <local-branch> <remote-branch>
git checkout <local-branch>

When you want to add your commits to the remote branch, first update your local to the current remote state, then push your commits:

git pull --rebase
git push origin <local-branch>:<remote-branch>

Working with stable branches

The remote stable branches are named as follows:

origin/KDE/4.6

To set up a local stable branch to track the remote stable branch:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

To then push changes to the remote stable branch:

git push origin KDE/4.6:KDE/4.6

Creating / Deleting Remote Branches

To create a new remote branch simply push your current branch to it:

git push origin <local-branch>:<remote-branch>

To delete a remote branch is a little obscure:

git push origin :<remote-branch>

Tracking Branches

To create a new branch that tracks an existing local or remote branch:

git branch --track <new-branch> <existing-branch>

To change the branch the current branch is tracking to a different local or remote branch:

git branch --set-upstream <existing-branch> <new-upstream-branch>

Cherry Picking

Cherry picking is a way to copy a single commit from any local or remote branch to your current local branch. You can even add any remote repository you want to your local clone to cherry-pick from.

git cherry-pick <original-commit>

When cherry picking between stable and unstable branches, always use the following form:

git cherry-pick -e -x <original-commit>

Common Options:

-e will allow you to edit the commit message to add any extra details and to change the BUG/CCBUG/FIXED-IN messages.

-x will automatically add the original commit number to the end of the commit message to enable better tracing and to simplify merging. Only do this if the original commit was already published in a public repository, e.g. your are forward porting or back porting the patch.

-n will cherry-pick the changes but not commit them to the new branch. This is very useful if you need to do further work on a commit.

Interactive Rebasing

If you have many commits in a branch that you want to clean up before pushing to the central repository, then you can use interactive rebasing to merge, split, delete, re-order or edit them.

To work with all commits to a branch:

git rebase -i <parent-branch>

where <parent-branch> is the branch you want to rebase onto. This is usually the branch that you based the original local branch off or are remotely tracking, but can be any branch you want.

To work with just the last n commits you made to a branch:

git rebase -i HEAD^n

HEAD^ is the terminology for saying "commit prior to head". HEAD~ works too. HEAD^^ would indicate 2 commits back, and so forth.

See http://book.git-scm.com/4_interactive_rebasing.html for full details.

Viewing What You've Changed

To see the difference between your tracked but unstaged changes and the current branch (including your not-yet-pushed commits)

git diff
git diff <filename>

To see the difference between your staged changes and the current branch (including your not-yet-pushed commits):

git diff --staged
git diff --staged <filename>

To see a list of commits to a branch:

git log

To see the details and diff for a commit

git show <commit>

Stashing Changes

If you have changes you don't wish to commit but don't want to lose either while you do something else, you can temporarily 'stash' the changes away. This could be some frequently used debug code,or just some work in progress you need to move to another branch without committing. If the code is just WIP for the current branch we recommend using an interim commit instead.

The stash is a temporary store that holds a stack of uncommitted changes at a repository level. Commands given below work by default with the stash at the top of the stack, or you can optionally provide the stack reference.

To store your current changes at the top of the stash stack:

git stash <optional comment>

For example:

git stash "My debug code"

To see all your stashed items in the stash stack:

git stash list

This will show something like:

stash@{0}: WIP on master: 6ebd0e2... My debug code
stash@{1}: WIP on master: 9cc0589... My stashed changes

To see the details of an individual stash:

git stash show <optional stash ref>

To see the stash at the top of the stack:

git stash show

To see the second item from top:

git stash show stash@{1}

To restore a stash while keeping a copy in the stack:

git stash apply <optional stash ref>

To restore a stash and remove it from the stack:

git stash pop <optional stash ref>

To remove a single stash from the stack without applying it:

git stash drop <optional stash ref>

To clear out your entire stash stack:

git stash clear

For more details see:

http://www.kernel.org/pub/software/scm/git/docs/git-stash.html
http://book.git-scm.com/4_stashing.html