Development/Git/Simple Workflow: Difference between revisions

    From KDE TechBase
    Line 52: Line 52:
    === Seeing What You Changed ===
    === Seeing What You Changed ===


    To see what files have been changed:


    git status
    To see what code changes have been made but not yet staged:
    git diff
    git diff <filename>
    To see what code changes have been staged but not committed:
    git diff --staged
    git diff --staged <filename>
    To see all the commits made:
    git log
    To see what changes were made in a commit:
    git show <sha5>
    The Git diff, log and show commands have many options for changing what is shown.  In particular diff can show the difference between any two commits.


    === Committing Your Changes ===
    === Committing Your Changes ===

    Revision as of 14:29, 11 June 2011

    DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

    Simple Workflow

    This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the Feature Branch Workflow.

    In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).

    The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.

    More detailed information can be found on the main KDE Git page.

    Set-up

    This section documents how to set up Git and your code repository for development.

    Configure Git

    Follow all the instructions on the KDE Git Configuration page, the instructions given below assume you are using the standard configuration.

    Clone your repository

    You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

    To clone your project repository:

    cd your/source/dir
    git clone kde:<project>
    cd <project>
    

    In our KFoo example:

    git clone kde:kfoo
    cd kfoo
    

    See the KDE Build Environment page for advice on structuring your source directory.

    If you have a slow or intermittent internet connection then you may prefer to download a snapshot tarball to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

    wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz
    

    Basic Actions

    This section documents basic actions that are performed within your workflow.

    See also the KDE Git Recipes page.

    Making changes

    Changing code is no different from when using subversion.

    Seeing What You Changed

    To see what files have been changed:

    git status
    

    To see what code changes have been made but not yet staged:

    git diff
    git diff <filename>
    

    To see what code changes have been staged but not committed:

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

    To see all the commits made:

    git log
    

    To see what changes were made in a commit:

    git show <sha5>
    

    The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference between any two commits.

    Committing Your Changes

    Merging Your Changes

    Local Feature Development

    Local Bug Fixing

    If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

    If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the Feature Branch Workflow.

    The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the Feature Branch Workflow.

    First, find out the name of the stable branch you want to bug fix:

    git branch -r
    

    This will list all the branches on the central repository, for example kdelibs includes the following branches:

     origin/HEAD -> origin/master
     origin/KDE/4.5
     origin/KDE/4.6
     origin/kdecore/klocale-win
     origin/kdeui/kdatetimeedit
     origin/master
    

    Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

    Next, create a local branch pointing to the stable release branch you want to bug fix:

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

    If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

    git checkout KDE/4.6
    git pull --rebase
    

    Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

    git commit -a
    

    Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

    Now you can merge your changes into the central code repository:

    git pull --rebase
    git push origin KDE/4.6:KDE/4.6    //TODO or use git merge???
    

    The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

    git checkout master
    git pull --rebase
    

    Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

    git cherry-pick -x -e <sha5 of stable commit>
    

    This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

    Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

    git pull --rebase
    git push origin master:master    //TODO or use git merge???