Difference between revisions of "Iegitaddmd"
| (6 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
This article is meant to describe use cases, work flow and the reasoning used when developing the commands. For instructions on how to use the command specifically in Stata and for a complete list of the options available, see the help files by typing <code>help iegitaddmd</code> in Stata. | This article is meant to describe use cases, work flow, and the reasoning used when developing the commands. For instructions on how to use the command specifically in [[Stata Coding Practices|Stata]] and for a complete list of the options available, see the help files by typing <code>help iegitaddmd</code> in '''Stata'''. | ||
== Read First == | == Read First == | ||
* Empty folders are ignored by GitHub and therefore not shared across project teams, but in research, we often want to share template folder structures for new projects where some folders might be empty. | * Empty [[DataWork Folder|folders]] are ignored by [[Getting Started with GitHub|GitHub]] and therefore are not shared across project teams, but in research, we often want to share template folder structures for new projects where some folders might be empty. | ||
* | * <code>iegitaddmd</code> is used to create placeholder files in empty folders so that project folder structures can be shared on '''GitHub''' even if some folders are note yet populated with project files. | ||
* This command is a part of the package [[Stata_Coding_Practices#ietoolkit|ietoolkit]] | * This command is a part of the package [[Stata_Coding_Practices#ietoolkit|ietoolkit]]. To install all the commands in this package, type <code>ssc install ietoolkit</code> in [[Stata Coding Practices|Stata]]. | ||
== Intended use cases == | == Intended use cases == | ||
It is common and highly recommended to use folder templates for new projects. Many organizations | It is common and highly recommended to use [[DataWork Folder|folder]] templates for new projects. Many organizations have folder structures templates and at DIME we have developed a command that set ups the folder structure for a new project with just one line of code. See [[iefolder]]. <code>iefolder</code> can also add more folders to a project folder that was initially set up with <code>iefolder</code>. For example, you can add an endline folder with sub-folders to a project folder that had only a ''baseline'' folder before. | ||
When folder templates are used to create a project folder or add a survey round folder it is common that empty folders are created. For example, templates often include | When folder templates are used to create a project folder or add a [[DataWork Survey Round|survey round folder]], it is common that empty folders are created. For example, templates often include an Output folder where [[Data Analysis|analysis output]] will be stored, but that folder will remain empty while the [[Master Dataset|dataset]] is [[Data Cleaning|cleaned]] and prepared for '''analysis'''. Let's say two people, person A and person B, collaborate on a project using [[Getting Started with GitHub|GitHub]], and person B used a template like <code>iefolder</code> to create the project folder. If person A were the first to do the '''analysis''', then there would be no Output folder where person A can store the outputs. Person A could of course create an output folder and call it anything, but that would defy the whole purpose of using a template in the first place. | ||
iegitaddmd provides a solution to this. It creates a placeholder file in any empty folder called README.md in the project folder specified. | <code>iegitaddmd</code> provides a solution to this. It creates a placeholder file in any empty folder called ''README.md'' in the project folder specified. These folders can then be included in a commit on '''GitHub'''. You may remove these files as soon as these folders are populated with project files, but a better practice might be to update the text to describe and document the files in that folder. | ||
Instead of the README.md file iegitaddmd produces you can specify a file saved to your computer that you want to use as placeholder file. It is strongly recommended that you use a raw text file format for this file, such as .md, .txt etc. Any code file like .do, .sthlp, .R, .py etc. are also raw text formats. If the format is .md and the file is named README (like the default file created by iegitaddmd) then the content of the file is displayed in the browser when someone browses to that folder on github.com. | Instead of the ''README.md'' file <code>iegitaddmd</code> produces, you can specify a file saved to your computer that you want to use as placeholder file. It is strongly recommended that you use a raw text file format for this file, such as .md, .txt etc. Any code file like .do, .sthlp, .R, .py etc., are also raw text formats. If the format is .md and the file is named ''README'' (like the default file created by <code>iegitaddmd</code>), then the content of the file is displayed in the browser when someone browses to that folder on github.com. | ||
=== Intended Work Flow === | === Intended Work Flow === | ||
Since this command is intended to be used on projects using GitHub, this section assumes basic understanding of GitHub terminology. | Since this command is intended to be used on projects using [[Getting Started with GitHub|GitHub]], this section assumes basic understanding of '''GitHub''' terminology. | ||
'''General work flow''' | '''General work flow''': if you are collaborating on a project using '''GitHub''' and if you have empty folders that you want to share with all collaborators on the project, use <code>iegitadd</code> on the top folder and a place holder file will be added to the folder or any subfolder that is currently empty. | ||
'''Work flow with iefolder''' | '''Work flow with [[iefolder]]''': the intended work flow together with <code>iefolder</code> is that you first use <code>iefolder</code> to create a project folder and then create the [[DataWork Survey Round|survey round]] and/or [[Unit of Observation|unit-of-observation]] folders that you need immediately using the ''round'' and ''unitofobs'' options. Then commit the files created by <code>iefolder</code> before moving on. Then use <ode>iegitaddmd</code> to populate all empty folders with placeholder files so that the full folder structure can be committed to the repository. Since both these two commands create many files and because the types of files are very different (<code>iefolder</code> creates files intended to be used, but <code>iegitaddmd</code> only creates placeholder files), it is best practice to split this into two separate commits where the purpose of the files can be explained differently. Technically, however, it can be done in one commit. When you want to add more '''survey round''' and/or '''unit-of-observation''' folders later into your project, you simply repeat these two steps to share the full folder structure of the newly added folders. | ||
=== Special Use Case === | === Special Use Case === | ||
If a folder in your repository includes files that all are ignored by the gitignore settings, then GitHub will not sync that folder, but iegitaddmd will not consider that folder empty and therefore not create a placeholder file. This means that this folder will not be synced. One solution to this would be to use the | If a folder in your repository includes files that all are ignored by the [[Getting Started with GitHub#gitignore files|gitignore settings]], then '''GitHub''' will not sync that folder, but <code>iegitaddmd</code> will not consider that folder empty and therefore not create a placeholder file. This means that this folder will not be synced. One solution to this would be to use the "all" option that tells <code>iegitaddmd</code> to create a placeholder file in all folders, which obviously also include folders where all files are '''gitignored'''. However, if the number of folders like this is few, and you know which they are, another solution might just be to copy a placeholder file to that folder manually. | ||
== Instructions == | == Instructions == | ||
These instructions are meant to help you understand how to use the command. For technical instructions on how to implement the command in Stata see the help files by typing <code>help iegitaddmd</code> in Stata. | These instructions are meant to help you understand how to use the command. For technical instructions on how to implement the command in [[Stata Coding Practices|Stata]] see the help files by typing <code>help iegitaddmd</code> in '''Stata'''. | ||
'''Warning''' | '''Warning''': if you by accident set the [[DataWork Folder|folder]] to your system root folder, <code>iegitaddmd , folder("C:\")</code> on a Windows computer or <code>iegitaddmd , folder("/Users/")</code> on a Mac, then the placeholder file will be created in every single folder on your computer even in system folders where it could cause major issues to your computer. Always double check that you indicate the full folder path in the ''folder()'' option. | ||
== Reasoning used during development == | == Reasoning used during development == | ||
The file created is of format .md (markdown) and called README.md as this is a special file name recognized by GitHub. The content of the file will be displayed, formatted in markdown format, in the web browser when someone | The file created is of format .md (markdown) and called ''README.md'' as this is a special file name recognized by [[Getting Started with GitHub|GitHub]]. The content of the file will be displayed, formatted in markdown format, in the web browser when someone browses folder on github.com that contains the ''README.md'' file. We strongly recommend that you use this same name and format if you use your own file instead of the default file created by <code>iegitaddmd</code>. | ||
== Related Pages == | == Related Pages == | ||
Latest revision as of 16:58, 9 August 2023
This article is meant to describe use cases, work flow, and the reasoning used when developing the commands. For instructions on how to use the command specifically in Stata and for a complete list of the options available, see the help files by typing help iegitaddmd in Stata.
Read First
- Empty folders are ignored by GitHub and therefore are not shared across project teams, but in research, we often want to share template folder structures for new projects where some folders might be empty.
iegitaddmdis used to create placeholder files in empty folders so that project folder structures can be shared on GitHub even if some folders are note yet populated with project files.- This command is a part of the package ietoolkit. To install all the commands in this package, type
ssc install ietoolkitin Stata.
Intended use cases
It is common and highly recommended to use folder templates for new projects. Many organizations have folder structures templates and at DIME we have developed a command that set ups the folder structure for a new project with just one line of code. See iefolder. iefolder can also add more folders to a project folder that was initially set up with iefolder. For example, you can add an endline folder with sub-folders to a project folder that had only a baseline folder before.
When folder templates are used to create a project folder or add a survey round folder, it is common that empty folders are created. For example, templates often include an Output folder where analysis output will be stored, but that folder will remain empty while the dataset is cleaned and prepared for analysis. Let's say two people, person A and person B, collaborate on a project using GitHub, and person B used a template like iefolder to create the project folder. If person A were the first to do the analysis, then there would be no Output folder where person A can store the outputs. Person A could of course create an output folder and call it anything, but that would defy the whole purpose of using a template in the first place.
iegitaddmd provides a solution to this. It creates a placeholder file in any empty folder called README.md in the project folder specified. These folders can then be included in a commit on GitHub. You may remove these files as soon as these folders are populated with project files, but a better practice might be to update the text to describe and document the files in that folder.
Instead of the README.md file iegitaddmd produces, you can specify a file saved to your computer that you want to use as placeholder file. It is strongly recommended that you use a raw text file format for this file, such as .md, .txt etc. Any code file like .do, .sthlp, .R, .py etc., are also raw text formats. If the format is .md and the file is named README (like the default file created by iegitaddmd), then the content of the file is displayed in the browser when someone browses to that folder on github.com.
Intended Work Flow
Since this command is intended to be used on projects using GitHub, this section assumes basic understanding of GitHub terminology.
General work flow: if you are collaborating on a project using GitHub and if you have empty folders that you want to share with all collaborators on the project, use iegitadd on the top folder and a place holder file will be added to the folder or any subfolder that is currently empty.
Work flow with iefolder: the intended work flow together with iefolder is that you first use iefolder to create a project folder and then create the survey round and/or unit-of-observation folders that you need immediately using the round and unitofobs options. Then commit the files created by iefolder before moving on. Then use <ode>iegitaddmd to populate all empty folders with placeholder files so that the full folder structure can be committed to the repository. Since both these two commands create many files and because the types of files are very different (iefolder creates files intended to be used, but iegitaddmd only creates placeholder files), it is best practice to split this into two separate commits where the purpose of the files can be explained differently. Technically, however, it can be done in one commit. When you want to add more survey round and/or unit-of-observation folders later into your project, you simply repeat these two steps to share the full folder structure of the newly added folders.
Special Use Case
If a folder in your repository includes files that all are ignored by the gitignore settings, then GitHub will not sync that folder, but iegitaddmd will not consider that folder empty and therefore not create a placeholder file. This means that this folder will not be synced. One solution to this would be to use the "all" option that tells iegitaddmd to create a placeholder file in all folders, which obviously also include folders where all files are gitignored. However, if the number of folders like this is few, and you know which they are, another solution might just be to copy a placeholder file to that folder manually.
Instructions
These instructions are meant to help you understand how to use the command. For technical instructions on how to implement the command in Stata see the help files by typing help iegitaddmd in Stata.
Warning: if you by accident set the folder to your system root folder, iegitaddmd , folder("C:\") on a Windows computer or iegitaddmd , folder("/Users/") on a Mac, then the placeholder file will be created in every single folder on your computer even in system folders where it could cause major issues to your computer. Always double check that you indicate the full folder path in the folder() option.
Reasoning used during development
The file created is of format .md (markdown) and called README.md as this is a special file name recognized by GitHub. The content of the file will be displayed, formatted in markdown format, in the web browser when someone browses folder on github.com that contains the README.md file. We strongly recommend that you use this same name and format if you use your own file instead of the default file created by iegitaddmd.