<commit_before># apex-source-control
Scripts for bringing Oracle Application Express applications into version control, any version control tool may be used.
Scripts are designed to work with Linux and OSX (Will not work on Windows).
These scripts were designed using [this paper] (http://www.rwijk.nl/AboutOracle/psdua.pdf) as reference.
If you have questions about workflow or any other concepts you should look for answers there first.
## Setup
#### Required files and environment variables
For these scripts to work you need the APEXExport.class and APEXExportSplitter.class which come with [APEX] (http://www.oracle.com/technetwork/developer-tools/apex/downloads/index.html) as well as [ojdbc6.jar] (http://www.oracle.com/technetwork/apps-tech/jdbc-112010-090769.html) which comes with Oracle database.
Note: you don't need to have oracle or apex installed locally, you just need the aforementioned files and a particular directory structure.

If you've extracted APEX then you need to set the APEX_HOME variable using:

	export APEX_HOME=/path/to/apex

where path/to/apex is the directory where you extracted APEX. You'll probably want to add this to your bash profile.

The scripts will look for the required .class files in $APEX_HOME/utilities/oracle/apex/ so if you're only using the .class files set up the directory structure and APEX_HOME variable accordingly.

If you have a local installation of Oracle database your ORACLE_HOME variable should already be set so just need to ensure that you have the ojdbc6.jar file at $ORACLE_HOME/jdbc/lib/ojdbc6.jar.
Otherwise, if you only have the ojdbc6.jar file, make a directory somewhere, set the relevant environment variable using

	export ORACLE_HOME=/path/to/your/dir

and put ojdbc6.jar at $ORACLE_HOME/jdbc/lib/ojdbc6.jar as mentioned before. Again you'll want to add the above line to your bash profile.

#### Setting up from an APEX export file
Note: If you already have an existing repository for the project you shouldn't use this method of installation, otherwise you may run into excessive version-control noise issues with conflicting object ids . This will likely only work if the the Export with Original IDs option was checked during export.

1) Make a local directory for your application:

	mkdir my-project

2) Run npm init, follow the given prompts and add the following line to your devDependencies in package.json

	"devDependencies": {
	    "apex-source-control" : "git+ssh://git@github.com:ntreeinc/apex-source-control.git"
	},

3) Add the following commands to your scripts in package.json

	"scripts": {
	   "apex-to-file" : "apex-source-control apex-to-file",
	   "file-to-apex" : "apex-source-control file-to-apex",
	   "new-conf-file" : "apex-source-control new-conf-file",
	   "switch-conf-file" : "apex-source-control switch-conf-file",
	   "read-conf-file" : "apex-source-control read-conf-file",
	   "generate-app-id" : "apex-source-control generate-app-id",
	   "uninstall-apex" : "apex-source-control uninstall-apex"
	},
If you want you can change the npm run commands to anything you'd like.

4) cd into node_modules/apex-source-control and run npm install, then link the scripts using the command 'npm link'. You may have to run this command as root.

5) Copy the export file into your project directory

6) Set up your classpath and run APEXExportSplitter

	export CLASSPATH=$APEX_HOME/utilities:$ORACLE_HOME/jdbc/lib/ojdbc6.jar
	java oracle.apex.APEXExportSplitter $export_file

7) Rename the generated directory to apex/

8) cd into apex/ and run:

	sed s^@application^@apex/application^ < install.sql > temp.sql
	rm -f install.sql
	mv temp.sql install.sql

We do this because we need to set the relative path to the install components from the top level directory

From here you can now either set up the project as a git/subversion/etc. repository or install into apex using 'npm run new-conf-file', enter data as needed; 'npm run switch-conf-file', switch to your new config file; and then 'npm run file-to-apex'.

#### Setting up from another APEX app

1) Make a local directory for your application:

	mkdir my-project

2) Run npm init, follow the given prompts and add the following line to your devDependencies in package.json

	"devDependencies": {
	    "apex-source-control" : "git+ssh://git@github.com:ntreeinc/apex-source-control.git"
	},

3) Add the following commands to your scripts in package.json

	"scripts": {
	   "apex-to-file" : "apex-source-control apex-to-file",
	   "file-to-apex" : "apex-source-control file-to-apex",
	   "new-conf-file" : "apex-source-control new-conf-file",
	   "switch-conf-file" : "apex-source-control switch-conf-file",
	   "read-conf-file" : "apex-source-control read-conf-file",
	   "generate-app-id" : "apex-source-control generate-app-id",
	   "uninstall-apex" : "apex-source-control uninstall-apex"
	},
If you want you can change the npm run commands to anything you'd like.

4) cd into node_modules/apex-source-control and run npm install, then link the scripts using the command 'npm link'. You may have to run this command as root.

5) Run the following commands and follow the prompts. The app id, parsing_schema, workspace_name and database connection info should all correspond to the app you want to download.
	
	npm run new-conf-file 		#create a config file with the info of the app you want to download
	npm run switch-conf-file 	#tell scripts to use the config file you just created
	npm run apex-to-file 		#download the app locally

You can now set up the application as a git or other version-control repository.

#### Setting up from a pre-existing repository

1) Clone the repository locally

2) Use 'npm install' to install dependencies

3) Run the following commands and follow the prompts. This will set up your config file and put the application into your APEX workspace

	npm run new-conf-file 		#create config file with the info of the app you want to use for version control
	npm run switch-conf-file 	#tell scripts to use the config file you just created
	npm run file-to-apex 		#download the app locally
That's it!

When you run 'npm run new-conf-file' you can either enter the info of the app you are already using to develop (your version will be overwritten by the one in version control) or enter in the info of a non-existent app which will be automatically created after running 'npm run file-to-apex'


## npm scripts Commands
##### npm run apex-to-file
Turn your apex workspace project into a file directory suitable for version control tools
##### npm run file-to-apex
Import your file directory into apex as an apex application. This command will only work with a $PROJECT_HOME/apex/ dir which was generated by APEXExportSplitter
##### npm run uninstall-apex
Uninstall your app from apex
##### npm run create-new-app
Currently not an availible command, may be added in the future.
##### npm run new-conf-file
Creates a new config file using user input. NOTE: As of right now you must run 'npm run switch-conf-file' command to change to the new config file after creating a new one
##### npm run switch-conf-file
Switches which config file is being used
##### npm run read-conf-file
Outputs the name and contents of the config file currently being used

###Workflow
TODO write workflow section 

###Config File Explained
May later add this section explaining each of the config parameters

###Known Issues
#### Deleting a page will always win merges
**To Reproduce**: 
* Have two developers working on different versions of an app (i.e. working on different features to be added).
* Developer 1 deletes a page in the app and pushes to the project's repo.
* Developer 2 merges developer 1's changes and decides to keep the deleted page in the merge.
* When developer 2 reinstalls the app into apex the page will still be deleted.

**Why it occurs**:

Since a page was deleted, it's removed from the install.sql script generated by apex. When git sees the merge of the two developers, only one has changed the install.sql script so it automatically applies those changes to the merge meaning the page is no longer called during install so it's never created in your apex application.

**How to avoid**:

Be extremely cautious when deleting pages and consult with your teammates first

**How to fix**:

If you do end up accidently deleting a page then you will have to manually re-add the install lines to the install.sql

#### Random version control noise in application meta-data
<commit_msg>Updated README according to feedback<commit_after># apex-source-control
Scripts for bringing Oracle Application Express applications into version control, any version control tool may be used.
Scripts are designed to work with Linux and OSX (Will not work on Windows).
These scripts were designed using [this paper] (http://www.rwijk.nl/AboutOracle/psdua.pdf) as reference.
If you have questions about workflow or any other concepts you should look for answers there first.
## Setup
#### Required files and environment variables
For these scripts to work you need the APEXExport.class and APEXExportSplitter.class which come with [APEX] (http://www.oracle.com/technetwork/developer-tools/apex/downloads/index.html) as well as [ojdbc6.jar] (http://www.oracle.com/technetwork/apps-tech/jdbc-112010-090769.html) which comes with Oracle database.
Note: you don't need to have oracle or apex installed locally, you just need the aforementioned files and a particular directory structure.

If you've extracted APEX then you need to set the APEX_HOME variable using:

	export APEX_HOME=/path/to/apex

where path/to/apex is the directory where you extracted APEX. You'll probably want to add this to your bash profile.

The scripts will look for the required .class files in $APEX_HOME/utilities/oracle/apex/ so if you're only using the .class files set up the directory structure and APEX_HOME variable accordingly.

If you have a local installation of Oracle database your ORACLE_HOME variable should already be set so just need to ensure that you have the ojdbc6.jar file at $ORACLE_HOME/jdbc/lib/ojdbc6.jar.
Otherwise, if you only have the ojdbc6.jar file, make a directory somewhere, set the relevant environment variable using

	export ORACLE_HOME=/path/to/your/dir

and put ojdbc6.jar at $ORACLE_HOME/jdbc/lib/ojdbc6.jar as mentioned before. Again you'll want to add the above line to your bash profile.

#### Setting up from an APEX export file
Note: If you already have an existing repository for the project you shouldn't use this method of installation, otherwise you may run into excessive version-control noise issues with conflicting object ids . This will likely only work if the the Export with Original IDs option was checked during export.

1) Make a local directory for your application:

	mkdir my-project

2) In the new directory run npm init and follow the given prompts, then add the following line to your devDependencies in package.json

	"devDependencies": {
	    "apex-source-control" : "git+ssh://git@github.com:ntreeinc/apex-source-control.git"
	},

3) Run npm install and then add the following commands to your scripts in package.json

	"scripts": {
	   "apex-to-file" : "apex-source-control apex-to-file",
	   "file-to-apex" : "apex-source-control file-to-apex",
	   "new-conf-file" : "apex-source-control new-conf-file",
	   "switch-conf-file" : "apex-source-control switch-conf-file",
	   "read-conf-file" : "apex-source-control read-conf-file",
	   "generate-app-id" : "apex-source-control generate-app-id",
	   "uninstall-apex" : "apex-source-control uninstall-apex"
	},
If you want you can change the npm run commands to anything you'd like.

4) cd into node_modules/apex-source-control and run npm install, then link the scripts using the command 'npm link'. You may have to run this command as root.

5) Copy the export file into your project directory

6) Set up your classpath and run APEXExportSplitter

	export CLASSPATH=$APEX_HOME/utilities:$ORACLE_HOME/jdbc/lib/ojdbc6.jar
	java oracle.apex.APEXExportSplitter $export_file
The CLASSPATH variable does not need to be added to your bash profile

7) Rename the generated directory to apex/

8) cd into apex/ and run:

	sed s^@application^@apex/application^ < install.sql > temp.sql
	rm -f install.sql
	mv temp.sql install.sql

We do this because we need to set the relative path to the install components from the top level directory

9) Remove the old $export_file or place it in a different directory

From here you can now either set up the project as a git/subversion/etc. repository or install into apex using 'npm run new-conf-file', enter data as needed; 'npm run switch-conf-file', switch to your new config file; and then 'npm run file-to-apex'.

#### Setting up from another APEX app

1) Make a local directory for your application:

	mkdir my-project

2) In the new directory run npm init and follow the given prompts, then add the following line to your devDependencies in package.json

	"devDependencies": {
	    "apex-source-control" : "git+ssh://git@github.com:ntreeinc/apex-source-control.git"
	},

3) Run npm install and then add the following commands to your scripts in package.json

	"scripts": {
	   "apex-to-file" : "apex-source-control apex-to-file",
	   "file-to-apex" : "apex-source-control file-to-apex",
	   "new-conf-file" : "apex-source-control new-conf-file",
	   "switch-conf-file" : "apex-source-control switch-conf-file",
	   "read-conf-file" : "apex-source-control read-conf-file",
	   "generate-app-id" : "apex-source-control generate-app-id",
	   "uninstall-apex" : "apex-source-control uninstall-apex"
	},
If you want you can change the npm run commands to anything you'd like.

4) cd into node_modules/apex-source-control and run npm install, then link the scripts using the command 'npm link'. You may have to run this command as root.

5) Run the following commands and follow the prompts. The app id, parsing_schema, workspace_name and database connection info should all correspond to the app you want to download.
	
	npm run new-conf-file 		#create a config file with the info of the app you want to download
	npm run switch-conf-file 	#tell scripts to use the config file you just created
	npm run apex-to-file 		#download the app locally

You can now set up the application as a git or other version-control repository.

#### Setting up from a pre-existing repository

1) Clone the repository locally

2) Use 'npm install' to install dependencies

3) Run the following commands and follow the prompts. This will set up your config file and put the application into your APEX workspace

	npm run new-conf-file 		#create config file with the info of the app you want to use for version control
	npm run switch-conf-file 	#tell scripts to use the config file you just created
	npm run file-to-apex 		#download the app locally
That's it!

When you run 'npm run new-conf-file' you can either enter the info of the app you are already using to develop (your version will be overwritten by the one in version control) or enter in the info of a non-existent app which will be automatically created after running 'npm run file-to-apex'


## npm scripts Commands
##### npm run apex-to-file
Turn your apex workspace project into a file directory suitable for version control tools
##### npm run file-to-apex
Import your file directory into apex as an apex application. This command will only work with a $PROJECT_HOME/apex/ dir which was generated by APEXExportSplitter
##### npm run uninstall-apex
Uninstall your app from apex
##### npm run create-new-app
Currently not an availible command, may be added in the future.
##### npm run new-conf-file
Creates a new config file using user input. NOTE: As of right now you must run 'npm run switch-conf-file' command to change to the new config file after creating a new one
##### npm run switch-conf-file
Switches which config file is being used
##### npm run read-conf-file
Outputs the name and contents of the config file currently being used

###Workflow & Project Sanitation
* Ignore config files in version control (.gitignore for git)
Your config files 

TODO write workflow section 

###Config File Explained
May later add this section explaining each of the config parameters

###Known Issues
#### Deleting a page will always win merges
**To Reproduce**: 
* Have two developers working on different versions of an app (i.e. working on different features to be added).
* Developer 1 deletes a page in the app and pushes to the project's repo.
* Developer 2 merges developer 1's changes and decides to keep the deleted page in the merge.
* When developer 2 reinstalls the app into apex the page will still be deleted.

**Why it occurs**:

Since a page was deleted, it's removed from the install.sql script generated by apex. When git sees the merge of the two developers, only one has changed the install.sql script so it automatically applies those changes to the merge meaning the page is no longer called during install so it's never created in your apex application.

**How to avoid**:

Be extremely cautious when deleting pages and consult with your teammates first

**How to fix**:

If you do end up accidently deleting a page then you will have to manually re-add the install lines to the install.sql

#### Random version control noise in application meta-data

{'fraction_non_alphanumeric': 0.0715729882733522, 'fraction_numerical': 0.004563572295072497, 'mean_word_length': 4.198798798798799, 'pattern_counts': {'":': 8, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 14, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '691697', 'n_tokens_mistral': 5069, 'n_tokens_neox': 4698, 'n_words': 2377}