[General Paranoid Android Discussion] Anu6is:
This should act as a basic guide for improving your workflow while using repo/git

This takes into consideration that you already have the repo tool installed, initialized and synced.

You are still encouraged to read up on how Git actually works as this attempts to keep simple layman terms

Useful guide - http://source.android.com/source/developing.html

Basic terms

HEAD - A pointer to the current active commit (top commit of the current branch)

Branch - Alternate working path, keeps it's own history and modifications

Unstaged - Git keeps track of all file changes regardless of if they are committed or not.

This allows you to select which changes you want to commit without having to first revert your changes.

To stage a change, you'll need to execute the command git add

Staged - Once you perform git add on a modified file, it's now staged and ready for committing.

Note:

You can build and test modified files without actually staging or committing them

You however, cannot push upstream changes without first committing those changes

Basic commands:

repo start (used to create a new branch with one or more projects)

repo start branchName projectPath projectPath2 ...

git add (used to stage modified/new files)

git add pathAndFileName
git add .

git rm (used to stage deleted files)

git rm pathAndFileName
git add -u

git diff (used to compare file changes, shows the diff between HEAD and the current project state)

git diff
git diff fileName

When diff is executed, if a file is not specified, it shows the difference between all files changed

The file being compared is shown at the top of the analysis, followed by it's differences

Deleted lines start with a minus (-) sign

New lines start with a plus (+) sign

Lines starting with @@ are simply line numbers within the file

Example: changing one line in AndroidManifest.xml

[B]diff --git a/AndroidManifest.xml b/AndroidManifest.xml[/B]
index e5ce889..5b8c41e 100644
--- a/AndroidManifest.xml
+++ b/AndroidManifest.xml
[COLOR="RoyalBlue"]@@ -1581,7 +1581,7 @@[/COLOR]
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<action android:name="android.app.action.START_ENCRYPTION" />
[COLOR="Red"]- <category android:name="android.intent.category.DEFAULT" /> />[/COLOR]
[COLOR="SeaGreen"]+ <category android:name="android.intent.category.DEFAULT" />[/COLOR]
</intent-filter>
<meta-data android:name="com.android.settings.FRAGMENT_CLASS"

git status (shows the status of modified files, staged or unstaged)

git status -s

git commit (commits your staged files to the working directory)

git commit -a
git commit -m [message]
git commit --amend

git remote (create a link to another repository for easy referrence)

git remote add remoteAlias remotePath
Example: git remote add Google [url]https://android.googlesource.com/platform/frameworks/base.git[/url]

git fetch (update your local copy of a remote branch, does not affect your working directory)

git fetch remoteAlias -branch

git pull (brings your repository up to date with a remote repository. Updates your working directory)

git pull remoteAlias - branch

git cherry-pick (fetches and merges files from a remote repository into your local repository)

git cherry-pick SHA

git log (lists all commits/commit history on your current branch)

git log

Recommended workflow

Notes on repo syncing

Repo sync pulls in all changes from the remote repository defined in your local manifest

and update your working directory to match the state of said repository.

Firstly, git will not overwrite any commit, so don't worry about that.

However, there are two ways that repo sync handles the upstream updates.

If you work on an unnamed or non-tracking branch, repo sync leaves your HEAD and switches to the tip of the branch specified in the manifest. This makes it appear as though your changes were deleted.

If you are on a tracking branch, repo sync will rebase your commits on top of the branch tip, after updating your working directory.

(i.e., re-apply your changes after the upstream updates so you now have updated remote files plus your own commits)

Recommendation: you should create a tracking branch before committing. This does not mean every time you want to commit you should start a new branch, but, for better workflow you should have at least one main tracked branch. For testing various new features/cherry-picks its best to branch first before committing.

repo start my_branch frameworks/base

Notes on repo start

- You are automatically switched to the new branch (for the specified projects only) once repo start branch is executed.

- New branches are created based on the HEAD of the remote repo in your manifest.

- Projects not specified for the new branch (in the repo start command) will remain on their current branch.

This is important to note because if changes present in branch1/ProjectB depend on code in branch1/ProjectA or branch1/ProjectC you will run into errors if branch2/(projectA or ProjectC) does not contain those required changes. To avoid this, simply repo start branch2/ProjectB as well, even if you don't intend to make changes to this project on your new branch. Of course, if there are no dependencies, there is no need to branch additional projects.

- Other projects can be added to an existing branch by simply running repo start again and using the existing branch name

- If you create a tracking branch, repo sync will rebase it automatically. So you don't have to do it by hand.

Notes on cherry-picking

Manual

git fetch remoteBranch

git cherry-pick commit_SHA

Automatic

login to gerrit

click the downloads tab

copy & paste cherry-pick link into the appropriate project path in terminal

Regardless of the method used, cherry-picking a commit will not always result in a clean merge.

If there is a conflict you will see a message similar to Prerecorded image for...

A bad merge does not mean bad code. It simply means your working directory is not at the same point

as the working directory used for the commit you are attempting to pick. This may be because you are

picking a commit from one ROM to another or the working directory was updated since the commit was

uploaded to gerrit

Conflicts must be cleared manually.

This is not the only thing you should look out for however, there may also be

-- Duplicated or deleted lines of code/resources

-- Unnecessary resources

-- Missing resources

Use git diff to see which files conflict and again to see the changes in those files. Of course you have to actually open those files and make your edits/fixes. Once edidted, simply commit the changes to the existing cherry-picked commit