Just check it out, using its local name.
E.g.,
git checkout release/current
1. Always use the local feature/api_doc as the starting point
git checkout feature/api_doc
2. Update your local repository
git fetch origin
3. Set the command options
When creating a new branch, set up configuration to mark the start-point branch as “upstream” from the new branch.
--track
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}”.
-l
The name of the new branch
"MobileUserDocs"
Issue the command
git branch –track -l MobileUserDocs
4. Checkout the new branch
And start working on the AuthID End User documentation.
checkout MobileUserDocs
5. Update your .gitignore file to exclude oXygen’s temp files
doc/user/v1/source/mobile-content/temp
6. Add the new content files to the local repo
Use Stage Changed to get all of the new source files, as well as the 3rdParty.css fileds, the tsmobile.ditamap file, the .project file, and the .gitignore file.
E.g., commit message
First draft of End User documentation.
- git clone git@git.c11.3rdParty.com:mobile_assets.git.
- git fetch –all.
- git checkout develop.
- git checkout -b feature/doc_update.
- git push origin feature/doc_update.
git merge origin/develop
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.
- 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.
- Accept revisions into the original file
In the bottom pane, accept each one in succession, and/or edit the content to your liking.
- When you’re done with that file, click File > Exit
This kicks you back to the Git BASH.
- 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.
- 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.
- From the git bash, enter the following command:
git push --tags
- 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.
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.
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
Assuming that you are currently in your working branch.
git fetch origin
git merge origin/develop
When the project is hosted privately on a remote Git server
Important! You must establish a VPN connection to the remote Git server.
- Open a Git bash prompt. You can simply click the shortcut on your Taskbar (or “C:Program Files (x86)Gitbinsh.exe” –login -i).
- 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
-
Using your web browser, navigate to the project site on GitHub (for example, https://github.com/3rdParty/java_3rdParty.git), and click “Fork.”
-
Navigate to your new forked version (https://github.com/%USERNAME%/java_3rdParty/).
-
Clone the new forked version (i.e., make a local working copy of it). To Clone from the Python Bash (the preferred method).
- Launch MINGW32 (click the icon in the Task Bar).
- 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.
- cd to the new enlistment directory (e.g., java_3rdParty).
- 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).
- Fetch from both origin and upstream. This brings in new branch ‘master’ -> upstream/master.
git fetch --all
- Create a new local branch called develop, and check it out.
git checkout -b develop
Switched to a new branch 'develop'
- 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
- git clone https://github.com/%USERNAME%/python_3rdParty_sdk.git.
- cd python_3rdParty.
- git remote add upstream https://github.com/3rdParty/python_3rdParty.git.
- git fetch –all. This fetches from both origin and upstream. This brings in new branch ‘master’ -> upstream/master.
- git checkout -b develop. This create a new branch called ‘develop’, based on a snapshot of ‘master’.
- git checkout -b feature/doc_update.
- git push origin feature/doc_update.
Allows you to visualize the project history as a branch map.
git gitk