Category: How to

Categories
Git How to

How to Merge New Completed Content into your Local feature/api Branch

Notes

It’s important that you execute a particular kind of merge. I.e., if you run a regular merge, all of your original individual commits will be transformed into one large fast-forward commit. A fast-forward only updates the HEAD pointer; it doesn’t create a commit object.

Note: You can’t just push the new commits into your mainline because the branch names differ. This can happen if another writer spawned and working branch, completed their work, and then merged their new content into your mainline (thus, advancing HEAD by one commit). Alternately, if you currently have another working branch with unfinished work. In both cases, all you have to do is execute git pull before you push, so it’s in synch with your mainline.

To can preserve the history of your revisions, you must specifying command line options:

  • Force “no fast forward” (–no-ff),
  • Show a difference statistic at the end of the merge (–stat),
  • Specify the use of the recursive strategy for the merge (-s recursive),
  • Specify that change priority be given to the new content (from in the source branch) (-X theirs),
  • Add a comment for the commit (-m).
Example

Merging the new content from /v1.4x_doc_update, into your local feature/api_doc branch.

git merge -s recursive -X theirs v1.43_doc_updates

Note: In Git terminology, the original content belongs to yours, and the new content belongs to theirs.

To avoid aborting an auto-merge when it hits a conflict (in particular, one that results from the insertion of a new item into the middle of a reference table), be sure to use the Recursive Merge Strategy, and use it with the theirs option. Why? Because this particular option forces conflicting content to be auto-resolved cleanly by favoring the new content.

Example
git merge -s recursive -X theirs v1.43_doc_updates

For more information, see: https://www.kernel.org/pub/software/scm/git/docs/git-merge.html.

1. Rebuild the docs

In Eclipse, click Run > Run History > 1 Rebuild HTML Docs.

2. Archive this doc build

Copy this version of the docs

Use this time-saving trick: Double-click the link below and Windows Explorer automatically opens, displaying the directory of the current build. Click anywhere in the contents pane, Select All (Ctrl+A), and copy everything to the Clipboard (Ctrl+C).

C:\Users\Chris\src\python_rest_api\doc\user\v1\build\html
Within this directory, create a new directory to hold this doc snapshot

Give it a name that indicates what made this doc version special. E.g., KeyPress.

Paste

Open the new directory, and paste the content of the Clipboard into it.

3. Make sure the working directory is clean

That is, make sure that you have no unstaged changes. In Eclipse, with the project folder selected in the PyDev Package Explorer, open the Git Staging tab, and click Refresh. If you have unstaged changes, stage them, and then commit them; and then go back and start again (from Step 1. Rebuild the docs).

4. Switch to the feature/api_doc branch

In Eclipse, right-click the project folder in the PyDev Package Explorer tab, and then click Team > Switch to > feature/api_doc.

Or from the git bash

Open a Git BASH, navigate to the current project working folder, and execute the following command:

$ git checkout feature/api_doc

5. Make sure your local branch is in sync (is up to date) with the remote repository

Update your local repository. This is a precautionary measure, in case the remote tracking branch has any commits that you don’t have locally. You didn’t do this once, and it caused you problems (which you easily solved by simply pulling – but it took you a while to figure out what the nature of the problems was).

Note: You must have a VPN connection to 3rdParty.

In Eclipse,

Right-click the project folder in the PyDev Package Explorer tab, and then click Team > Fetch from Upstream.

Or from the git bash
git fetch

6. Create the merge command line

Copy the example git command line below, to a new blank file in EditPad Pro, and revise the <comment/> and <branch_name/>, and then copy the line to the clip board.

git merge --stat --no-ff -m "<comment/>" -s recursive -X theirs <branch_name/>

E.g., (copy & paste from EditPad Pro)

git merge --stat --no-ff -m "Added HTTP status code 429 Too Many Requests" -s recursive -X theirs v1.43_updates

7. Execute the merge

At this point in time, I don’t know how to execute this command in Eclipse.

From the git bash

Click anywhere inside the Git command window, and then dump the contents of the clipboard onto the command line (Trick: right-click).

Note

 

The merge might have conflicts. If so, then run git mergetool.

Example
git merge --stat --no-ff -m "Added HTTP status code 429 Too Many Requests" -s recursive -X theirs v1.43_updates

8. How to resolve merge conflicts if any

Prerequesite: You’ve registered Beyond Compare 4 as the merge tool in the Git environment.

  1. Run the merge

From the Git BASH, execute the comnmand: git mergetool, and then press Return. Beyond Compare launches, and displays the original version of the file in the left pane, and the revised version in the right pane. The lines that conflict are highlighted.

  1. Accept revisions into the original file

In the bottom pane, accept each one in succession, and/or edit the content to your liking.

  1. When you’re done with that file, click File > Exit

This kicks you back to the Git BASH.

  1. If there’s another file conflict, just wrince & repeat

Press Return, and step through the conflicts in this file.

Note: At this point, the merge isn’t actually done, despite the fact that you’ve resolved all of the conflicts.

  1. Conclude the merge

Commit the merge object, and include an informative message.

git commit -m "Merged new content for R1.42 (Verify Registration)."

9. Push the new content upstream

That is, update remote refs along with the associated tree objects from your local feature/api_doc to origin feature/api_doc.

  1. From the git bash, enter the following command:
git push --tags
  1. Copy that last line (the one immediately above) so you can use it in the broadcast e-mail.
What to do when there isn’t yet, an upstream branch

You spell it out for Git. I.e., “Create a branch called ‘feature/doc_update’ in the origin repository”.

git push origin feature/doc_update

10. Check the local branch status

Just to make sure the push worked properly.

git status

11. Create a new branch for the next release

You should still have the feature/api_doc checked out, and it should now be up to date with respact to your latest bits. From here, spawn a new branch for your work for the next drop. From the Git BASH, enter the command:

git branch --track -l v1.4x_doc_updates

12. Send the broadcast email

Right after you push your doc updates to the origin repository, send a broadcast e-mail to the team summarizing the changes, asking for (making) a Pull Request, and CC PM (the PM distribution list).

Note: Set the Importance level to High.

In the body of the message, list the doc work items that went into this doc update. You can get this information quite easily in Eclipse. Simply select the Git Reflog tab. The line items of interest are the ones with “commit:” in the Reflog Messages.

E.g.

To: pm@3rdParty.com Importance: High

Subject: Pull Request: REST API Docs v1.51

I pushed a documentation update (To git@git.c11.3rdParty.com:python_rest_api.git 26d53cf..62ed6c1 feature/api_doc -> feature/api_docs ).

This update includes

  • TD-41 Fixed a broken link. “State Abbreviation Code” now links to http://pe.usps.com/text/pub28/28apb.htm.
  • TD-44 Changed Required to Optional, for the ‘ucid’ request parameter.
  • TD-45 Changed the default value for number of verification code digits that 3rdParty automatically generates by default from six, to five.
  • TD-48 Corrected two spelling mistakes.
  • TD-49 Corrected a spelling mistake.
  • TD-57 Added two new error codes:
    • -40008 [Product method] exceeded transaction hard cap; Request denied.
    • -60001 PhoneID Contact data not found).

Would you please pull from feature/api_docs, then rebuild the REST API doc set, and then publish it?

If this content update involved TechDoc bugs (Issues), then resolve them as fixed, and then add an appropriate comment

I incorporated this content update in v 1.51 of the REST API docs.

13. Increment the version number

Checkout the new branch. Open the file: doc/user/v1/source/conf.py. Rebuild the docs. Now the current doc build shows the upcoming release number.

14. Put the latest doc set up on Gullinx

Create a new directory. Copy the contents of C:\Users\Chris\src\python_rest_api\doc\user\v1\buildhtml.

Categories
Git How to

How to Create a New Branch for Tracking New Doc Work

New/revised content is always/only considered new/revised in reference to the latest content in the feature/api_doc branch (I like to refer to this branch as my “Mainline” branch). As such, always author your new/revised content in a new branch spawned off of the feature/api_doc branch. The neat thing about this approach is that when you’ve completed and vetted your new content, you can update the docs using git merge (you simply check-out the mainline branch, and then merge-in the working branch).

If, while you worked on the new content (in its working branch), the mainline didn’t change, then the difference between the two branches will be just the commits on the working branch.

  • If you merge the new content into feature/api_doc, it produces a Fast Forward. I.e,. feature/api_doc HEAD is advanced by one commit; it is a Merge Commit, and it contains all of the individual commits for incremental updates you made to the content in the working branch.
  • you can switch back to mainline, and then pull the new content just by merging the commits from the spawned branch into feature/api_doc. This type of version tracking allows you to do things like undoing a content revision by simply rolling-back the commit.

If the cloned project has no develop branch

git branch -l develop

git checkout develop

git push origin develop

git checkout -b feature/doc_update

git push origin feature/doc_update

git branch --track -l migrate_comments

git checkout migrate_comments

If you’re not already on the feature/api_doc branch, then switch over to it

git checkout feature/api_doc

Check to make sure the working directory is clean (just in case).

git status

Update your local repository

git fetch

or

git fetch origin

You can omit “origin” if your repo is already setup with a default path-spec. To find out, try running “git fetch” and see what happens.

Spawn a new branch off of feature/api_doc

This git command for this, along with its options, is somewhat complicated. Here’s a breakdown of the pieces.

Set the command options

When creating a new branch, mark the start-point branch as upstream from the new branch. Note that track needs two dashes. I noticed that when I pasted the command line into the BASH, one dash was missing!

--track

Note: At this point, I’m not sure if you need to track the starting branch though. Tracking is useful when the spawned-from branch keeps growing due to other people’s commits. In that case, you, along with each of the other contributers should each keep your working directory up to date with respect to the spawned-from branch. Why? Because the assumption is that everyone contributing to the project always contribute to the current state of it. Think of it as a way to simulate the same experience for each contributor as if they were working on the mainline, alone. In your case, there are no other contributers. As such, the spawned-from branch should never change. That is unless you work on more than one content update at a time.

Ok then: You definately do need to use that tracking feature because you sometimes have to have more than on working branches going at the same time. This has already happened, and you didn’t realize that after you’d merged the first woking branch’s content update into mainline, that you then needed to synchronize the second working branch with it (i.e., that you needed to checkout the second working branch, and then execute a “git pull” from it).

-l

Create the branch’s reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as “<branchname>@{yesterday}”.

Issue the command

It’s easiest if you simply copy & paste this command line example into a new document in EditPad Pro; and then modify it accordingly.

Note: I chose not to create and switch to the new branch in one operation using “git checkout -b” – because I wasn’t sure if I could still include the options I needed (–track and -l). I’ll experiment with this and see if it’s possible, and if it is, I’ll recommend that approach.

git branch --track -l v1.4x_updates

Branch v1.4x_updates set up to track local branch feature/api_doc.

Checkout the new branch

And start documenting the new feature.

git checkout v1.4x_updates

Switched to branch ‘v1.4x_updates’

Increment the doc build number

%GITSOURCE%\python_rest_api\doc\user\v1\source\conf.py

Add the new content files to the local repo

Use Stage Changed.

Categories
Git How to

How to Resolve a Merge Conflict

Usually when you run a merge, it results in a fast forward. But sometimes things aren’t so simple.

Here’s a typical scenario where you have to resolve a merge conflict.

First, you perform:

git fetch origin

and then, you perform:

git merge origin/develop

and it results in a merge conflict. Automatic merge failed; fix conflicts and then commit the result.

To Resolve the Conflict

git mergetool
Categories
Git How to

How to Sync to Develop

Assuming that you are currently in your working branch.

git fetch origin

git merge origin/develop
Categories
Git How to

How to get an Enlistment

When the project is hosted privately on a remote Git server

Important! You must establish a VPN connection to the remote Git server.

  1. Open a Git bash prompt. You can simply click the shortcut on your Taskbar (or “C:Program Files (x86)Gitbinsh.exe” –login -i).
  2. Make sure you’re in your GIT_HOME directory (%USERPROFILE%\src), and then execute the following commands.
git clone git@git.c11.3rdParty.com:python_rest_api.git

cd python_rest_api

git pull

git checkout feature/api_doc

When the project is hosted on GitHub

When a project is hosted on GitHub, you can’t push your changes to it. Instead, you have to submit a pull request. But you can only do that if you fork the project, and host your fork up on GitHub. But how can you work on content when you repository isn’t local? The answer is you “Clone in Desktop.” So,

The java 3rd party SDK

  1. Using your web browser, navigate to the project site on GitHub (for example, https://github.com/3rdParty/java_3rdParty.git), and click “Fork.”

  2. Navigate to your new forked version (https://github.com/%USERNAME%/java_3rdParty/).

  3. Clone the new forked version (i.e., make a local working copy of it). To Clone from the Python Bash (the preferred method).

    1. Launch MINGW32 (click the icon in the Task Bar).
    2. Execute: git clone https://github.com/%USERNAME%/java_3rdParty.git. Your forked repo on Github automatically becomes the remote for the cloned repo, called “origin”.

OR

To Clone using GitHub for Windows, you must have previously installed GutHub for Windows: http://windows.github.com/

Note

 

You’ll receive an e-mail message from github.com The following SSH key was added to your account: GitHub for Windows – Production 9d:86:da:ce:4b:e6:c6:d3:c7:47:57:c1:1b:32:f4:c7 If you believe this key was added in error, you can remove the key and disable access at the following location: https://github.com/settings/ssh

You must configure GutHub for Windows to downlad cloned repositories to your %USERPOFILE%/src/ directory. On your new forked repository web page, and click “Clone in Desktop”. Now you have a local, working copy of the project repository.

  1. cd to the new enlistment directory (e.g., java_3rdParty).
  2. Add the original source repo (under the 3rdParty GitHub account) as a remote named “upstream”.
git remote add upstream https://github.com/3rdParty/java_3rdParty.git

When you execute this command, nothing appears to happen (but something does).

  1. Fetch from both origin and upstream. This brings in new branch ‘master’ -> upstream/master.
git fetch --all
  1. Create a new local branch called develop, and check it out.
git checkout -b develop

Switched to a new branch 'develop'
  1. Create a new local branch called feature/doc_update, and check it out.
git checkout -b feature/doc_update

Your github enlistment for the Java sdk:

git@github.com:%USERNAME%/java_3rdParty.git
Note from Humnberto
Chris,
Please pull the latest version of the master branch into your branch and then repush. Run the following commands from your branch. If you haven’t already, please make sure that your upstream is configured.

https://help.github.com/articles/fork-a-repo

Commands to run after upstream has been configured.

git fetch upstream
git merge upstream/master

The python 3rd party SDK

To clone a local working enlistment
  1. git clone https://github.com/%USERNAME%/python_3rdParty_sdk.git.
  2. cd python_3rdParty.
  3. git remote add upstream https://github.com/3rdParty/python_3rdParty.git.
  4. git fetch –all. This fetches from both origin and upstream. This brings in new branch ‘master’ -> upstream/master.
  5. git checkout -b develop. This create a new branch called ‘develop’, based on a snapshot of ‘master’.
  6. git checkout -b feature/doc_update.
  7. git push origin feature/doc_update.
Categories
Git How to

How to Start gitk

Allows you to visualize the project history as a branch map.

git gitk
Categories
Git How to

How to Start the Git GUI

Allows you to use mouse clicks to perform git commands.

git gui